Overview

The Traces API lets services, agents, and CI jobs publish traces, synchronize messages, and read data from the namespace bound to an API key. This reference intentionally covers the reviewed external contract rather than every API used by the Traces web application.

Base URL

https://actions.traces.com

All JSON requests and responses use UTF-8. Successful JSON responses use an { "ok": true, "data": ... } envelope. Errors use { "ok": false, "error": { "code": "...", "message": "..." } }.

Authentication

Namespace admins can create and manage API keys from the organization's API settings. Regular members cannot list, create, update, or revoke keys. Send the key as a bearer token:

curl -X PUT https://actions.traces.com/v1/traces/ci-run-2026-08-13-001 \
  -H "Authorization: Bearer $TRACES_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"agentId":"codex","title":"Repair flaky retry tests"}'

API keys begin with trk_, belong to one namespace, and only access data in that namespace. Store keys in a secret manager or environment variable and never expose them in browser code or source control.

Scopes

Scope	Access
`traces:read`	List traces and read trace metadata and messages.
`traces:write`	Create or synchronize trace metadata and messages.
`namespace:read`	Read the API key's namespace metadata and members.

Endpoint groups

Namespaces

Read the namespace bound to an API key and list its members.

Traces

List and read traces, or synchronize metadata using a stable external ID.

Messages

Read messages or upload individual messages and batches.

IDs and timestamps

Write routes use stable trace and message IDs supplied by your integration. Reusing an ID updates the same resource, which makes uploads safe to retry. Trace read routes also accept a Traces internal ID. Timestamps are Unix time in milliseconds unless a field says otherwise.

Errors

Status	Meaning
`400`	The request or parameter values are invalid.
`401`	The API key is missing, invalid, expired, or revoked.
`403`	The key lacks a required scope or cannot access the requested namespace.
`404`	The target trace does not exist or is outside the key's namespace.
`429`	The caller exceeded a rate limit.
`500`	The server could not complete the request.
`503`	Trace and message writes are temporarily paused for maintenance.

Write requests are limited to 600 requests per minute per user. Individual read endpoints may apply separate limits.