curl --request GET \
--url https://albus.sh/api/traces/{invocation_key} \
--header 'Authorization: Bearer <token>'import requests
url = "https://albus.sh/api/traces/{invocation_key}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://albus.sh/api/traces/{invocation_key}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"invocation_key": "<string>",
"session_id": "<string>",
"status": "RUNNING",
"spans_expired": true,
"started_at": "2023-11-07T05:31:56Z",
"session_position": 2,
"spans": [
{
"id": "<string>",
"type": "invocation",
"status": "SUCCEEDED",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"parent_id": "<string>",
"attempt": 2,
"superseded": true,
"name": "<string>",
"error": "<string>",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123
},
"input": "<string>",
"input_bytes": 123,
"input_sha256": "<string>",
"input_truncated": true,
"output": "<string>",
"output_bytes": 123,
"output_sha256": "<string>",
"output_truncated": true
}
],
"agent_name": "<string>",
"agent_revision": "<string>",
"ended_at": "2023-11-07T05:31:56Z",
"failure": {
"kind": "crash",
"message": "The invocation failed. Try again."
},
"attempts": [
{
"attempt": 123,
"status": "RUNNING",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123
}
}
],
"next_cursor": "<string>"
}{
"message": "Invalid request parameters"
}{
"message": "Invalid or expired token"
}{
"message": "Resource not found"
}{
"message": "Trace spans are temporarily unavailable"
}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.
curl --request GET \
--url https://albus.sh/api/traces/{invocation_key} \
--header 'Authorization: Bearer <token>'import requests
url = "https://albus.sh/api/traces/{invocation_key}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://albus.sh/api/traces/{invocation_key}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"invocation_key": "<string>",
"session_id": "<string>",
"status": "RUNNING",
"spans_expired": true,
"started_at": "2023-11-07T05:31:56Z",
"session_position": 2,
"spans": [
{
"id": "<string>",
"type": "invocation",
"status": "SUCCEEDED",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"parent_id": "<string>",
"attempt": 2,
"superseded": true,
"name": "<string>",
"error": "<string>",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123
},
"input": "<string>",
"input_bytes": 123,
"input_sha256": "<string>",
"input_truncated": true,
"output": "<string>",
"output_bytes": 123,
"output_sha256": "<string>",
"output_truncated": true
}
],
"agent_name": "<string>",
"agent_revision": "<string>",
"ended_at": "2023-11-07T05:31:56Z",
"failure": {
"kind": "crash",
"message": "The invocation failed. Try again."
},
"attempts": [
{
"attempt": 123,
"status": "RUNNING",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123
}
}
],
"next_cursor": "<string>"
}{
"message": "Invalid request parameters"
}{
"message": "Invalid or expired token"
}{
"message": "Resource not found"
}{
"message": "Trace spans are temporarily unavailable"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The invocation's key — the value sent as its Idempotency-Key, or the one the server returned in that header when it was omitted.
1 - 255Query Parameters
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.
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.
final, all Opaque pagination cursor. Return only items positioned after it; pass a value obtained from a previous page to fetch the next one.
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.
1 <= x <= 500Response
OK
One agent invocation — what it ran, how it ended, and when.
The invocation's key — the value sent as its Idempotency-Key, or the one the server returned in that header when it was omitted.
The session this invocation belongs to.
How an invocation or one of its attempts ended, or RUNNING while it is still in flight.
RUNNING, SUCCEEDED, FAILED 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.
When the invocation was accepted.
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.
x >= 1A 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.
Show child attributes
Show child attributes
Name of the agent the invocation ran (e.g. "support-triage"). Absent for an invocation made before agent names were recorded.
The agent revision the invocation ran (e.g. "a1b2c3d4"). Absent for an invocation made before revisions were recorded.
When the invocation's outcome was recorded. Absent while it runs.
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.