API Reference
Traces
List, read, create, or synchronize trace metadata.
GET
/v1/tracesRequires the traces:read API key scope.
Authorization
apiKey AuthorizationBearer <token>
A namespace-scoped API key created in Traces organization settings.
In: header
Query Parameters
limit?number
gitRemoteUrl?string
Only return traces for this exact Git remote URL.
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/traces"{ "ok": true, "data": { "traces": [ { "id": "string", "externalId": "string", "title": "string", "agentId": "string", "model": "string", "visibility": "private", "createdAt": 0, "updatedAt": 0, "sourceCreatedAt": 0, "messageCount": 0, "tokenUsage": { "inputTokenCount": 0, "outputTokenCount": 0, "cacheReadTokenCount": 0, "cacheWriteTokenCount": 0, "reasoningTokenCount": 0, "totalInputTokenCount": 0 }, "author": { "id": "string", "displayName": "string", "avatarUrl": "string", "slug": "string" }, "agentCreator": { "id": "string", "name": "string", "slug": "string", "avatarUrl": "string" }, "relatedTo": "string", "relationshipType": "subagent", "downloadCount": 0, "ai_analysis": { "summary": "string", "status": "Planning", "steps": [ { "verb": "string", "text": "string" } ], "badges": [ "string" ], "keywords": [ "string" ] } } ] }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}GET
/v1/traces/{externalId}Requires the traces:read API key scope.
Authorization
apiKey AuthorizationBearer <token>
A namespace-scoped API key created in Traces organization settings.
In: header
Path Parameters
externalId*string
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/traces/string"{ "ok": true, "data": { "trace": { "id": "string", "externalId": "string", "title": "string", "agentId": "string", "model": "string", "visibility": "private", "createdAt": 0, "updatedAt": 0, "sourceCreatedAt": 0, "tokenUsage": { "inputTokenCount": 0, "outputTokenCount": 0, "cacheReadTokenCount": 0, "cacheWriteTokenCount": 0, "reasoningTokenCount": 0, "totalInputTokenCount": 0 }, "author": { "id": "string", "displayName": "string", "avatarUrl": "string", "slug": "string" }, "relatedTo": "string", "relationshipType": "subagent", "downloadCount": 0, "ai_analysis": { "summary": "string", "status": "Planning", "steps": [ { "verb": "string", "text": "string" } ], "badges": [ "string" ], "keywords": [ "string" ] }, "namespace": { "id": "string", "slug": "string" }, "createdBy": "string", "projectPath": "string", "projectName": "string", "gitRemoteUrl": "string", "gitBranch": "string", "gitRef": "string", "userName": "string", "userAvatar": "string", "userSlug": "string", "modelName": "string", "messageCount": 0, "agentCreator": { "id": "string", "name": "string", "slug": "string", "avatarUrl": "string" }, "relatedToTrace": { "id": "string", "relationshipType": "subagent", "title": "string", "startedAt": 0, "messageExternalId": "string" }, "relatedByTraces": { "items": [ { "id": "string", "relationshipType": "subagent", "title": "string", "startedAt": 0, "messageExternalId": "string" } ], "hasMore": true } } }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}PUT
/v1/traces/{externalId}Requires the traces:write API key scope.
Authorization
apiKey AuthorizationBearer <token>
A namespace-scoped API key created in Traces organization settings.
In: header
Path Parameters
externalId*string
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v1/traces/string" \ -H "Content-Type: application/json" \ -d '{ "agentId": "codex", "title": "Repair flaky retry tests", "visibility": "private" }'{ "ok": true, "data": { "trace": { "id": "string", "externalId": "string", "title": "string", "agentId": "string", "model": "string", "visibility": "private", "createdAt": 0, "updatedAt": 0, "sourceCreatedAt": 0, "tokenUsage": { "inputTokenCount": 0, "outputTokenCount": 0, "cacheReadTokenCount": 0, "cacheWriteTokenCount": 0, "reasoningTokenCount": 0, "totalInputTokenCount": 0 }, "author": { "id": "string", "displayName": "string", "avatarUrl": "string", "slug": "string" }, "relatedTo": "string", "relationshipType": "subagent", "downloadCount": 0, "ai_analysis": { "summary": "string", "status": "Planning", "steps": [ { "verb": "string", "text": "string" } ], "badges": [ "string" ], "keywords": [ "string" ] }, "namespace": { "id": "string", "slug": "string" }, "createdBy": "string", "projectPath": "string", "projectName": "string", "gitRemoteUrl": "string", "gitBranch": "string", "gitRef": "string", "userName": "string", "userAvatar": "string", "userSlug": "string", "modelName": "string", "messageCount": 0, "agentCreator": { "id": "string", "name": "string", "slug": "string", "avatarUrl": "string" }, "relatedToTrace": { "id": "string", "relationshipType": "subagent", "title": "string", "startedAt": 0, "messageExternalId": "string" }, "relatedByTraces": { "items": [ { "id": "string", "relationshipType": "subagent", "title": "string", "startedAt": 0, "messageExternalId": "string" } ], "hasMore": true } } }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}