> ## Documentation Index > Fetch the complete documentation index at: https://docs.get-exo.com/llms.txt > Use this file to discover all available pages before exploring further. # Ingest a session batch > Accept up to 500 coding-session events in one round trip and return immediately. Accept up to 500 coding-session events in one round trip and return immediately. This is the route a backfill should use. Events are queued under the credential's org and user in a single insert, with the same per-event deduplication as the single-event route, so a retried batch is reported as `deduped` rather than stored twice. Call `POST /v1/ingest/session-finalize` once the last batch is accepted. ## Authorization This route requires the `write` scope. A missing or invalid credential returns 401 [`authentication_error`](/errors/authentication_error). A valid credential without the scope returns 403 [`permission_denied`](/errors/permission_denied), and the problem body names the exact scope required. ## Headers These are request conventions the contract does not declare as parameters, so they do not appear in the schema tables below. | Header | Applies | What it does | | ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-Exo-API-Key` | Required | Your Exo API key, `exo__`. `Authorization: Bearer exo_...` is accepted as an alternate. | | `X-Exo-Subject` | Refused | This route scopes data by the key owner. Sending the header returns 400 [`subject_not_supported`](/errors/subject_not_supported), rather than silently reading the wrong partition. | | `Idempotency-Key` | Not honoured | This route does not replay: the same per-event deduplication covers a retried batch. | | `X-Request-Id` | Response | Returned on every response, including `204`s. Quote it in a support request. | ## Success responses | Status | Meaning | | ------ | --------------------------------------------------------- | | `202` | How many events were queued and how many were duplicates. | ## Errors | Status | Code | When | | ------ | ------------------------------------------------------ | -------------------------------------------------------------- | | `400` | [`invalid_request`](/errors/invalid_request) | Malformed request, for example an invalid cursor. | | `401` | [`authentication_error`](/errors/authentication_error) | Missing or invalid credentials. | | `403` | [`permission_denied`](/errors/permission_denied) | Missing scope, or an unprovisioned subject selector. | | `404` | [`not_found`](/errors/not_found) | The resource does not exist, or is not visible to this caller. | | `409` | [`conflict`](/errors/conflict) | A conflict with the current state of the resource. | | `422` | [`validation_error`](/errors/validation_error) | The request was understood but failed field validation. | | `429` | [`rate_limit_exceeded`](/errors/rate_limit_exceeded) | Rate limit exceeded. Retry after the Retry-After interval. | | `503` | [`service_degraded`](/errors/service_degraded) | A dependency is temporarily unavailable. Safe to retry. | Every error is an RFC 9457 `application/problem+json` body carrying a stable `code`, a `requestId`, and a `suggestedAction` where Exo has one. See [Errors](/platform/errors). ## Notes * **Up to 500 events per call.** This is the route a backfill should use. * **Call finalize once the last batch is accepted**, or the layers that session ingestion does not build on its own will not be built. ## OpenAPI ````yaml openapi.json POST /v1/ingest/session-batch openapi: 3.1.0 info: contact: name: Exo url: https://get-exo.com/ description: >- The Exo public developer API: ingest content, retrieve identity-conditioned context, and read the knowledge graph. Authenticate every request with an Exo API key, either as the X-Exo-API-Key header or as Authorization: Bearer exo_... . Errors follow RFC 9457 problem+json with a stable snake_case code on every body. title: Exo API version: 1.0.0 servers: - url: https://api.get-exo.com security: - ApiKeyHeader: [] - BearerAuth: [] tags: - name: retrieve x-group: Retrieval - name: search x-group: Search - name: ingest x-group: Ingestion - name: jobs x-group: Jobs - name: subjects x-group: Subjects - name: recall x-group: Recall - name: graph x-group: Graph - name: insights x-group: Contradictions and proposals - name: condition x-group: Condition - name: brain x-group: Brain - name: sessions x-group: Coding sessions - name: connectors x-group: Connectors - name: events x-group: Events and webhooks - name: meta x-group: Identity - name: keys x-group: Keys and sandbox - name: usage x-group: Usage - name: settings x-group: Settings - name: exports x-group: Exports - name: team x-group: Team - name: admin x-group: Account and purge paths: /v1/ingest/session-batch: post: tags: - sessions summary: Ingest a session batch description: >- Accept up to 500 coding-session events in one round trip and return immediately. This is the route a backfill should use. Events are queued under the credential's org and user in a single insert, with the same per-event deduplication as the single-event route, so a retried batch is reported as `deduped` rather than stored twice. Call `POST /v1/ingest/session-finalize` once the last batch is accepted. operationId: postIngestSessionBatch requestBody: content: application/json: schema: $ref: '#/components/schemas/IngestSessionBatchRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/IngestSessionBatchResponse' description: How many events were queued and how many were duplicates. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Malformed request, for example an invalid cursor. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Missing or invalid credentials. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Missing scope or unprovisioned subject. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: The requested resource does not exist. '409': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Conflict, for example a duplicate in-flight idempotent request. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Validation Error '429': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- Rate limit exceeded; retry after the interval in the Retry-After header. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: A dependency is temporarily unavailable; safe to retry with backoff. components: schemas: IngestSessionBatchRequest: description: 'POST /v1/ingest/session-batch: bulk from daemon + retroactive bootstrap.' properties: events: items: $ref: '#/components/schemas/SessionEvent' maxItems: 500 title: Events type: array required: - events title: IngestSessionBatchRequest type: object IngestSessionBatchResponse: properties: deduped: title: Deduped type: integer ingested: title: Ingested type: integer required: - ingested - deduped title: IngestSessionBatchResponse type: object Problem: description: |- RFC 9457 problem+json envelope (spec D9), documented in OpenAPI. Invariant: ``code`` equals the tail of the ``type`` URI (``https://docs.get-exo.com/errors/``). properties: code: title: Code type: string detail: title: Detail type: string documentationUrl: anyOf: - type: string - type: 'null' title: Documentationurl errors: anyOf: - items: $ref: '#/components/schemas/FieldViolation' type: array - type: 'null' title: Errors requestId: default: '' title: Requestid type: string status: title: Status type: integer suggestedAction: anyOf: - type: string - type: 'null' title: Suggestedaction title: title: Title type: string type: title: Type type: string required: - type - title - status - detail - code title: Problem type: object SessionEvent: description: |- A single Claude Code session-log line. Maps to one parsed line from a .jsonl session transcript (~/.claude/projects//.jsonl) or a sub-agent transcript (...//subagents/agent-*.jsonl). Sub-agent events have parent_session_id + agent_id populated. Dedup key on the server side: (user_id, line_uuid). Wire contract uses clean ``user_id`` / ``org_id`` field names (camelCase aliases on the wire). DB column mapping is handled at the SQL boundary in the ingest worker, not here. properties: agentId: anyOf: - type: string - type: 'null' title: Agentid authorRole: anyOf: - type: string - type: 'null' title: Authorrole claudeCodeVersion: title: Claudecodeversion type: string cwd: title: Cwd type: string gitBranch: anyOf: - type: string - type: 'null' title: Gitbranch lineTimestamp: format: date-time title: Linetimestamp type: string lineType: title: Linetype type: string lineUuid: minLength: 1 title: Lineuuid type: string orgId: minLength: 1 title: Orgid type: string parentSessionId: anyOf: - type: string - type: 'null' title: Parentsessionid payload: additionalProperties: true title: Payload type: object sessionId: minLength: 1 title: Sessionid type: string userId: minLength: 1 title: Userid type: string required: - userId - orgId - sessionId - lineUuid - lineType - lineTimestamp - cwd - claudeCodeVersion - payload title: SessionEvent type: object FieldViolation: description: A single field-level violation inside a Problem ``errors[]`` list. properties: code: title: Code type: string field: title: Field type: string message: title: Message type: string pointer: title: Pointer type: string required: - pointer - field - code - message title: FieldViolation type: object securitySchemes: ApiKeyHeader: description: An Exo API key (exo_...) sent as the X-Exo-API-Key header. in: header name: X-Exo-API-Key type: apiKey BearerAuth: description: The same Exo API key (exo_...) sent as an Authorization bearer token. scheme: bearer type: http ````