> ## Documentation Index > Fetch the complete documentation index at: https://docs.albus.sh/llms.txt > Use this file to discover all available pages before exploring further. # Search traces > Lists your organization's agent invocations, newest first, without their spans. Filter by agent name, agent revision, status, session, or start time to find the invocation you want, then read it with `GET /traces/{invocation_key}`. An invocation is listed as soon as it starts, and a filter that matches nothing returns an empty page rather than an error — except `session_id`, which is a `404` when your organization has no such session. Page with `after` and `limit`: pass the response's `next_cursor` as the next request's `after`, and keep requesting while `next_cursor` is present — you have reached the end when it is absent. A page can hold fewer invocations than `limit`, or none at all, and still have a `next_cursor`; a short page is not the end of the results. A listing covers the window given by `since` and `until`, and omitting `since` searches the last 31 days. The window is fixed when the first page is requested, so paging with `after` keeps returning results from the window that page used: `after` carries that window and the filters it was made with, so send it with no filters, or with every filter repeated exactly, and expect a `400` otherwise. ## OpenAPI ````yaml /openapi/openapi.yaml get /traces openapi: 3.0.3 info: title: Albus API description: Albus service REST API version: 1.0.0 servers: - url: https://albus.sh/api description: Production server - url: http://localhost:8080 description: Local development server security: - bearerAuth: [] - apiKey: [] tags: - name: Agents description: Inspect the agents that have run in your organization. - name: Auth description: Identify the authenticated user. - name: Health description: Check service availability. - name: Memories description: Read and delete what your agents remember. - name: Models description: Discover the models available to run agents on. - name: Secrets description: Manage secrets available to agent sessions. - name: Sessions description: Run and inspect agent sessions. - name: Tokens description: Manage organization API keys. - name: Traces description: Find your agent invocations and read what they did. paths: /traces: get: tags: - Traces summary: Search traces description: > Lists your organization's agent invocations, newest first, without their spans. Filter by agent name, agent revision, status, session, or start time to find the invocation you want, then read it with `GET /traces/{invocation_key}`. An invocation is listed as soon as it starts, and a filter that matches nothing returns an empty page rather than an error — except `session_id`, which is a `404` when your organization has no such session. Page with `after` and `limit`: pass the response's `next_cursor` as the next request's `after`, and keep requesting while `next_cursor` is present — you have reached the end when it is absent. A page can hold fewer invocations than `limit`, or none at all, and still have a `next_cursor`; a short page is not the end of the results. A listing covers the window given by `since` and `until`, and omitting `since` searches the last 31 days. The window is fixed when the first page is requested, so paging with `after` keeps returning results from the window that page used: `after` carries that window and the filters it was made with, so send it with no filters, or with every filter repeated exactly, and expect a `400` otherwise. operationId: listTraces parameters: - name: agent_name in: query required: false description: > Return only invocations of this agent (e.g. "support-triage"). Invocations with no recorded agent name are not matched. schema: type: string maxLength: 255 - name: agent_revision in: query required: false description: > Return only invocations of this exact agent revision (e.g. "a1b2c3d4"). Combines with `agent_name`. Invocations with no recorded revision are not matched. schema: type: string maxLength: 255 - name: status in: query required: false description: > Return only invocations with this outcome. An invocation whose spans have aged out is still matched by the outcome it recorded. schema: $ref: '#/components/schemas/TraceStatus' - name: session_id in: query required: false description: > Return only invocations of this session — the session identifier you ran it with. A session you do not have is a `404`. schema: type: string minLength: 2 maxLength: 100 pattern: ^[0-9a-zA-Z._:-]+$ - name: since in: query required: false description: > Return only invocations that started at or after this time. Defaults to 31 days ago; pass it to search further back. schema: type: string format: date-time - name: until in: query required: false description: > Return only invocations that started at or before this time. Defaults to now, and must be after `since`; an earlier `until` is a `400`. schema: type: string format: date-time - $ref: '#/components/parameters/AfterCursor' - $ref: '#/components/parameters/TraceLimit' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListTracesResponse' '400': description: Invalid cursor or filter content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' '404': description: No session with the requested `session_id` content: application/json: schema: $ref: '#/components/schemas/ErrNotFound' security: - bearerAuth: [] - apiKey: [] components: schemas: TraceStatus: type: string enum: - RUNNING - SUCCEEDED - FAILED description: > How an invocation or one of its attempts ended, or `RUNNING` while it is still in flight. ListTracesResponse: type: object required: - traces properties: traces: type: array items: $ref: '#/components/schemas/TraceSummary' description: > This page of invocations, newest first. It can hold fewer than `limit`, or none at all, while `next_cursor` is present. next_cursor: type: string description: > Cursor for the next page. Pass it as `after`, with no filters or with every filter this listing used repeated exactly, to fetch the following traces. Present whenever there may be more traces, however few this page returned; omitted only once there are none left. ErrBadRequest: type: object required: - message properties: message: type: string description: Human-readable error message example: Invalid request parameters ErrUnauthorized: type: object required: - message properties: message: type: string description: Human-readable error message example: Invalid or expired token ErrNotFound: type: object required: - message properties: message: type: string description: Human-readable error message example: Resource not found TraceSummary: type: object description: One agent invocation — what it ran, how it ended, and when. required: - invocation_key - session_id - status - spans_expired - started_at properties: invocation_key: type: string description: > The invocation's key — the value sent as its Idempotency-Key, or the one the server returned in that header when it was omitted. session_id: type: string description: The session this invocation belongs to. agent_name: type: string description: > Name of the agent the invocation ran (e.g. "support-triage"). Absent for an invocation made before agent names were recorded. agent_revision: type: string description: > The agent revision the invocation ran (e.g. "a1b2c3d4"). Absent for an invocation made before revisions were recorded. status: $ref: '#/components/schemas/TraceStatus' spans_expired: type: boolean description: > Whether the invocation's spans have aged out. Spans are kept for the retention window (currently 90 days) from the invocation's start; the invocation itself is kept, so `status` and the fields beside it stay readable past it. started_at: type: string format: date-time description: When the invocation was accepted. ended_at: type: string format: date-time description: | When the invocation's outcome was recorded. Absent while it runs. parameters: AfterCursor: name: after in: query required: false description: > Opaque pagination cursor. Return only items positioned after it; pass a value obtained from a previous page to fetch the next one. schema: type: string TraceLimit: name: limit in: query required: false description: > Maximum number of traces to return. A page can be shorter, so page while `next_cursor` is present. schema: type: integer minimum: 1 maximum: 100 default: 10 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT apiKey: type: http scheme: bearer description: Org-scoped API key issued via POST /tokens ````