API Reference
Messages
Upload individual messages or message batches.
PUT
/v1/traces/{externalId}/messages/{messageId}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
messageId*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/messages/string" \ -H "Content-Type: application/json" \ -d '{ "idScheme": "v2", "order": 1, "parts": [ { "content": { "text": "Implemented bounded exponential backoff." }, "externalId": "part-001", "type": "text" } ], "role": "assistant", "textContent": "Implemented bounded exponential backoff.", "timestamp": 1722470400000 }'{ "ok": true, "data": { "message": { "id": "string", "externalId": "string", "sourceKey": "string", "role": "user", "textContent": "string", "model": "string", "order": 0, "timestamp": 0, "parts": [ { "externalId": "string", "sourceKey": "string", "type": "text", "content": {}, "order": 0, "tokenUsage": { "inputTokenCount": 0, "outputTokenCount": 0, "cacheReadTokenCount": 0, "cacheWriteTokenCount": 0, "reasoningTokenCount": 0, "totalInputTokenCount": 0 } } ], "tokenUsage": { "inputTokenCount": 0, "outputTokenCount": 0, "cacheReadTokenCount": 0, "cacheWriteTokenCount": 0, "reasoningTokenCount": 0, "totalInputTokenCount": 0 } } }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}{ "ok": false, "error": { "code": "string", "message": "string", "details": {} }}POST
/v1/traces/{externalId}/messages/batchRequires 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
Stable trace ID assigned by your integration.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/v1/traces/string/messages/batch" \ -H "Content-Type: application/json" \ -d '{ "idScheme": "v2", "messages": [ { "externalId": "msg-001", "order": 0, "parts": [ { "content": { "text": "Add bounded retries." }, "externalId": "part-001", "type": "text" } ], "role": "user", "textContent": "Add bounded retries." } ] }'{ "data": { "messages": 1 }, "ok": true}