> ## Documentation Index > Fetch the complete documentation index at: https://docs.primeintellect.ai/llms.txt > Use this file to discover all available pages before exploring further. # Upload traces > Upload traces as a `multipart/form-data` request with two parts: * `metadata` (`application/json`): `{"schema_version": 1, "context": {...}}`. `context` is an optional flat string map stored on every trace in the upload. * `traces` (`application/x-ndjson`): one complete trace per line, or one complete episode per line with `X-Prime-Line-Format: episode`. The part may be sent with `Content-Encoding: gzip`. `Idempotency-Key` is `sha256:<64 lowercase hex>` of the uncompressed `traces` bytes, newlines included, and is also the upload ID. A request can be up to 256 MiB and a single line up to 64 MiB, both measured uncompressed. `201` means every line was stored; there is no partial success. `400` means the content was rejected and nothing was stored. `409` means the same bytes were already uploaded with a different line format. `429` and `503` are safe to retry with the same bytes after `Retry-After`. ## OpenAPI ````yaml https://prime-traces.pintel.dev/openapi.json post /api/v1/traces openapi: 3.1.0 info: title: Prime Traces description: > Upload, query and delete training, evaluation and inference traces. Authenticate with a Prime Intellect API key that has the **Prime Traces** permission, sent as `Authorization: Bearer `. Send `X-Prime-Team-ID` to act on a team's traces instead of your personal ones. Errors share one envelope, `{"error": {"code", "message", "details?"}}`, where `code` is stable and safe to branch on. version: '0' servers: - url: https://prime-traces.pintel.dev security: [] paths: /api/v1/traces: post: tags: - Ingestion summary: Upload traces description: >- Upload traces as a `multipart/form-data` request with two parts: * `metadata` (`application/json`): `{"schema_version": 1, "context": {...}}`. `context` is an optional flat string map stored on every trace in the upload. * `traces` (`application/x-ndjson`): one complete trace per line, or one complete episode per line with `X-Prime-Line-Format: episode`. The part may be sent with `Content-Encoding: gzip`. `Idempotency-Key` is `sha256:<64 lowercase hex>` of the uncompressed `traces` bytes, newlines included, and is also the upload ID. A request can be up to 256 MiB and a single line up to 64 MiB, both measured uncompressed. `201` means every line was stored; there is no partial success. `400` means the content was rejected and nothing was stored. `409` means the same bytes were already uploaded with a different line format. `429` and `503` are safe to retry with the same bytes after `Retry-After`. operationId: upload_traces_api_v1_traces_post parameters: - name: x-prime-line-format in: header required: false schema: anyOf: - type: string - type: 'null' description: '`trace` (the default) or `episode`.' title: X-Prime-Line-Format description: '`trace` (the default) or `episode`.' - name: x-prime-team-id in: header required: false schema: anyOf: - type: string - type: 'null' description: >- Act on this team's traces instead of your personal ones. You must be a member of the team. title: X-Prime-Team-Id description: >- Act on this team's traces instead of your personal ones. You must be a member of the team. - name: Idempotency-Key in: header required: true description: >- `sha256:<64 lowercase hex>` of the uncompressed `traces` part; it is also the upload ID. schema: type: string pattern: ^sha256:[0-9a-f]{64}$ requestBody: required: true content: multipart/form-data: schema: type: object required: - metadata - traces properties: metadata: additionalProperties: false description: >- The `metadata` part: `{ schema_version, context? }`. The digest is not restated here — it is the `Idempotency-Key`, and it is also the upload ID. properties: schema_version: type: integer title: Schema Version context: additionalProperties: type: string type: object title: Context required: - schema_version title: UploadMetadata type: object traces: type: string format: binary description: >- JSONL: one trace per line, or one episode per line under `X-Prime-Line-Format: episode`. May be gzip-encoded. encoding: metadata: contentType: application/json traces: contentType: application/x-ndjson responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UploadAccepted' '400': description: Malformed upload content. Nothing was stored. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 'Missing or malformed `Authorization: Bearer ` header.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The upload would cross the retained-storage cap, the API key lacks the `traces` write permission (`forbidden`), or Prime Traces is not enabled for this account (`service_not_enabled`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- These bytes conflict with an earlier upload of the same content (`line_format_conflict`, `source_conflict`, `upload_attribution_conflict`). Retrying will not help. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: >- Another attempt at this upload is already in flight. Retry with the same bytes after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Ingest capacity or storage is temporarily unavailable. Retry with the same bytes after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - PrimeApiKey: [] components: schemas: UploadAccepted: properties: upload_id: type: string title: Upload Id status: $ref: '#/components/schemas/UploadStatus' default: committed type: object required: - upload_id title: UploadAccepted description: '201 body. `status` is always `committed`: there is no partial success.' ErrorResponse: properties: error: $ref: '#/components/schemas/ErrorBody' type: object required: - error title: ErrorResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError UploadStatus: type: string enum: - received - committed - indexed - invalidated - index_requeued - index_skipped title: UploadStatus description: >- States an upload can hold in `upload_events`. Content addressing bounds an upload at two events: `received`, then one terminal state. A refused upload appends nothing — the rejection is raised at the first bad line, before the digest that would prove the upload was this upload — so the upload simply stays `received` and the next attempt is read again. ErrorBody: properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string title: Message details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details type: object required: - code - message title: ErrorBody ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ErrorCode: type: string enum: - upload_too_large - trace_too_large - too_many_traces_in_episode - episode_id_too_long - environment_id_too_long - too_many_traces_in_upload - duplicate_trace_id - duplicate_episode_id - digest_mismatch - line_format_mismatch - malformed_encoding - invalid_trace - invalid_metadata - created_at_out_of_window - unsupported_schema_version - unknown_episode_reference - line_format_conflict - source_conflict - upload_attribution_conflict - billing_intent_required - invalid_idempotency_key - invalid_cursor - invalid_filter - search_limit_exceeded - unauthenticated - forbidden - service_not_enabled - auth_unavailable - trace_not_found - trace_not_indexed - run_not_found - episode_not_found - export_job_not_found - task_already_running - invalid_schedule_time - snapshot_not_due - statement_production_incomplete - statement_production_failed - rate_limited - writer_pool_saturated - ingest_capacity_exceeded - ingest_unavailable - storage_unavailable - index_task_queue_unavailable - internal_error title: ErrorCode securitySchemes: PrimeApiKey: type: http description: A Prime Intellect API key with the Prime Traces permission. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.