> ## 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. # Get one invocation's trace > Returns one agent invocation and a page of its spans in chronological order — the model calls it made and the tool calls they requested, with their payloads. 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 spans than `limit`, or none at all, and still have a `next_cursor`; a short page is not the end of the spans. An invocation that was retried has more than one attempt, and by default only the spans of the latest attempt come back — the one that produced its outcome, or the one still in flight: the attempts before it are hidden, so a retried invocation reads as one history. They are hidden, not absent — every attempt ran, spent tokens, and may have made tool calls whose effects stand — so `attempts` lists all of them with their own outcomes and token usage, and `attempts=all` returns their spans too, each marked `superseded`. A span becomes readable seconds after it happens, so an invocation still in flight can return fewer spans than it has already taken. A payload can come back shortened, or left out when it is too large — `input` and `output` say when, and `*_bytes`, `*_sha256` and `*_truncated` describe the complete value where the span carries them. Reading the shape of an invocation without its payloads is a request with `payloads=false`: the same spans with their timings, statuses and token usage, and `limit` up to 500, so a whole trace usually fits in one request. Spans age out after a retention window: past it `spans_expired` is true and no spans come back, while the invocation itself stays readable. ## OpenAPI ````yaml /openapi/openapi.yaml get /traces/{invocation_key} 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/{invocation_key}: parameters: - $ref: '#/components/parameters/InvocationKey' get: tags: - Traces summary: Get one invocation's trace description: > Returns one agent invocation and a page of its spans in chronological order — the model calls it made and the tool calls they requested, with their payloads. 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 spans than `limit`, or none at all, and still have a `next_cursor`; a short page is not the end of the spans. An invocation that was retried has more than one attempt, and by default only the spans of the latest attempt come back — the one that produced its outcome, or the one still in flight: the attempts before it are hidden, so a retried invocation reads as one history. They are hidden, not absent — every attempt ran, spent tokens, and may have made tool calls whose effects stand — so `attempts` lists all of them with their own outcomes and token usage, and `attempts=all` returns their spans too, each marked `superseded`. A span becomes readable seconds after it happens, so an invocation still in flight can return fewer spans than it has already taken. A payload can come back shortened, or left out when it is too large — `input` and `output` say when, and `*_bytes`, `*_sha256` and `*_truncated` describe the complete value where the span carries them. Reading the shape of an invocation without its payloads is a request with `payloads=false`: the same spans with their timings, statuses and token usage, and `limit` up to 500, so a whole trace usually fits in one request. Spans age out after a retention window: past it `spans_expired` is true and no spans come back, while the invocation itself stays readable. operationId: getTrace parameters: - name: payloads in: query required: false description: > Whether to include what each span was given and produced. `true`, the default, returns `input` and `output` and the fields that describe them. `false` returns the same spans without them — everything the span recorded about itself: `id`, `parent_id`, `type`, `name`, `status`, `started_at`, `ended_at` and `usage` — which is the cheap way to read an invocation's shape, and it lets `limit` go up to 500. `after` carries the mode it was made with, so page with the same `payloads` you started with and expect a `400` otherwise. schema: type: boolean default: true - name: attempts in: query required: false description: > Which attempts to return spans for. `final`, the default, returns only the spans of the latest attempt — the one that produced the invocation's outcome, or the one still in flight; `all` also returns the spans of the attempts before it, each marked `superseded`. Either way `attempts` in the response lists every attempt that ran. schema: type: string enum: - final - all default: final - $ref: '#/components/parameters/AfterCursor' - $ref: '#/components/parameters/TraceSpanLimit' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TraceResponse' '400': description: Invalid cursor content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrNotFound' '503': description: > The invocation's spans could not be read. Retry the request; the invocation and its spans are unaffected. headers: Retry-After: description: | Seconds to wait before retrying, when a wait is known to help. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrUnavailable' security: - bearerAuth: [] - apiKey: [] components: parameters: InvocationKey: name: invocation_key in: path required: true 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. schema: type: string minLength: 1 maxLength: 255 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 TraceSpanLimit: name: limit in: query required: false description: > Maximum number of spans to return. With payloads at most 25, which is also the default; with `payloads=false` at most 500, and 500 by default, so one request usually returns a whole trace. A `limit` above the bound for the mode you asked for is a `400`. A page can be shorter, so page while `next_cursor` is present. schema: type: integer minimum: 1 maximum: 500 schemas: TraceResponse: allOf: - $ref: '#/components/schemas/TraceSummary' - type: object required: - spans - session_position properties: failure: allOf: - $ref: '#/components/schemas/TraceFailure' description: > Why the invocation failed. Present only when `status` is `FAILED`, and readable past the retention window, since it comes from the invocation rather than its spans. Read it here rather than from `GET /traces`, which reports only that an invocation failed — listing a page of reasons costs a lookup per invocation on it. session_position: type: integer minimum: 1 description: > Which invocation of its session this is, counting from 1 in the order they were created — the same number as the `inv` segment of every span's id, so you do not have to read an id to know which invocation you are holding. Invocations are only ever appended, so a position never changes. spans: type: array items: $ref: '#/components/schemas/TraceSpan' description: > A page of the invocation's spans, oldest first, from its latest attempt unless `attempts=all` asked for the earlier attempts as well. It can hold fewer than `limit`, or none at all, while `next_cursor` is present. Empty once `spans_expired` is true. attempts: type: array items: $ref: '#/components/schemas/TraceAttempt' description: > Every attempt of the invocation, oldest first, whichever attempts `spans` came from — so one entry means it ran once, and more than one means the attempts before the last produced nothing that reached its output, while still spending tokens and making any tool calls they made. Read them with `attempts=all`. Absent once `spans_expired` is true. next_cursor: type: string description: > Cursor for the next page. Pass it as `after` to fetch the following spans. Present whenever there may be more spans, however few this page returned; omitted once there are none left, including once `spans_expired` is true. 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 ErrUnavailable: type: object required: - message properties: message: type: string description: Human-readable error message example: Trace spans are temporarily unavailable 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. TraceFailure: type: object description: Why an invocation failed, and what to show for it. required: - kind - message properties: kind: type: string description: > Failure classification: "crash" (unexpected exit or signal), "no_progress" (the harness stalled and was force-killed), "interrupted" (the invocation could not continue), or "internal" (the invocation could not start). example: crash message: type: string description: The sentence recorded for this failure. example: The invocation failed. Try again. TraceSpan: type: object description: > One span of an invocation — a model call, a tool call it requested, or a level of the invocation above them. required: - id - type - status - started_at - ended_at properties: id: type: string description: > Where the span sits in its session, as a dotted path you can read: `inv2` is the invocation itself — the second invocation of its session — `inv2.attempt1.step3` one step of it, a model call and the tool calls it requested, `inv2.attempt1.step3.model` that step's model call, and `inv2.attempt1.step3.tool1` a tool call it requested, numbered in the order it requested them. Every count starts at 1, no segment is ever `0`, and `.model` is a slot rather than a count, so a step has exactly one. `inv2.attempt1` is not a span you can fetch: an attempt is not a span, so a step's parent is the invocation, and only a model or tool call's parent is its own id without its last segment. The attempt segment is what keeps an id from being reused: the same step of a second attempt is `inv2.attempt2.step3`, never a fresh `inv2.attempt1.step3` under an id you have already read. An id comes from the span itself, not from the page or the attempts you asked for, so the same span has the same id on every page, under `attempts=final` and under `attempts=all`, and across requests. Ids are unique within a session, so the spans of several of a session's invocations read as one tree with the session as its root. parent_id: type: string description: > Id of the span this one belongs to: for a model call or a tool call, this span's id without its last segment; for a step, the invocation itself — an attempt is not a span. Absent only for the invocation. It is present even when the span it names is not in this response: the invocation is published once it has ended and a step once that step has ended, so a still-running invocation has spans whose parent is not there yet, which is not an error. Treat a parent you cannot find as one you do not have. attempt: type: integer minimum: 1 description: > Which attempt of the invocation this span belongs to, counting from 1 — the same number as the second segment of its `id`, so a retry is visible without reading the id. Absent on the invocation itself, which belongs to no single attempt. superseded: type: boolean description: > Whether this span belongs to an attempt that was tried again, so nothing it produced reached the invocation's output. Only `attempts=all` returns such spans, and what they did still stands: their tokens were spent and their tool calls had their effects. Absent on a span of the latest attempt. type: type: string enum: - invocation - step - model_call - tool_call description: > The kind of span (e.g. "invocation" for the invocation itself, "step" for one step, "model_call" for a model call, "tool_call" for a tool call it requested). name: type: string description: > The model or tool the span called (e.g. "WEB_SEARCH"). Absent for a span that called neither. status: type: string enum: - SUCCEEDED - FAILED description: | Whether the span succeeded. Only finished spans are returned. error: type: string description: > Why the span failed. Absent when it succeeded. A long message is shortened, and then carries the same `[omitted: N of M bytes; sha256=…]` marker a payload does. started_at: type: string format: date-time description: When the span began. ended_at: type: string format: date-time description: When the span finished. usage: $ref: '#/components/schemas/TokenUsage' input: type: string description: > What the span was given. A shortened value carries its head and tail separated by a `[omitted: N of M bytes; sha256=…]` marker; a model call's payloads are left out entirely when the span records too much to keep. A tool call's input is the one that comes with `input_bytes` and `input_sha256`. input_bytes: type: integer format: int64 description: | Size of the complete input, when known. input_sha256: type: string description: | SHA-256 of the complete input, when known. input_truncated: type: boolean description: > Whether `input` is shortened or left out, when known. A left-out payload carries neither `input_bytes` nor `input_sha256`; the invocation's own shortened input carries no `input_truncated` either. output: type: string description: > What the span returned. A shortened value carries its head and tail separated by a `[omitted: N of M bytes; sha256=…]` marker; a model call's payloads are left out entirely when the span records too much to keep. A tool call's output is the one that comes with `output_bytes` and `output_sha256`. output_bytes: type: integer format: int64 description: | Size of the complete output, when known. output_sha256: type: string description: | SHA-256 of the complete output, when known. output_truncated: type: boolean description: > Whether `output` is shortened or left out, when known. A left-out payload carries neither `output_bytes` nor `output_sha256`; the invocation's own shortened output carries no `output_truncated` either. TraceAttempt: type: object description: > One attempt of an invocation. An invocation is attempted again when an attempt cannot be finished, and every attempt starts the agent's work over: an attempt before the last one spent its own tokens and may have made tool calls whose effects stand, even though nothing it produced reached the invocation's output. required: - attempt - status - started_at properties: attempt: type: integer format: int32 description: > Which attempt this is, counting from 1. The last one is the attempt that produced the invocation's outcome, or the one still in flight, and the one whose spans come back unless `attempts=all` is requested. status: $ref: '#/components/schemas/TraceStatus' started_at: type: string format: date-time description: When the attempt began. ended_at: type: string format: date-time description: When the attempt ended. Absent while it runs. usage: $ref: '#/components/schemas/TokenUsage' 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. TokenUsage: type: object description: Tokens consumed. Absent when none were recorded. properties: input_tokens: type: integer format: int64 output_tokens: type: integer format: int64 total_tokens: type: integer format: int64 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT apiKey: type: http scheme: bearer description: Org-scoped API key issued via POST /tokens ````