Overview
Publish trace metadata and messages with a namespace-scoped API key.
The Traces Ingestion API lets services, agents, and CI jobs publish trace metadata and synchronize messages. This reference intentionally covers the supported ingestion contract rather than the APIs used by the Traces web application.
Base URL
https://actions.traces.comAll JSON requests and responses use UTF-8. Successful JSON responses use an { "ok": true, "data": ... } envelope. Errors use { "ok": false, "error": { "code": "...", "message": "..." } }.
Authentication
Create and manage API keys from the organization's API settings, then 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:write | Create or synchronize trace metadata and messages. |
Endpoint groups
Traces
Create or synchronize trace metadata using a stable external ID.
Messages
Upload individual messages or batches with stable external IDs.
IDs and timestamps
Trace and message IDs in ingestion routes are stable IDs supplied by your integration. Reusing an ID updates the same resource, which makes uploads safe to retry. 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.