> ## Documentation Index > Fetch the complete documentation index at: https://docs.xtrace.ai/llms.txt > Use this file to discover all available pages before exploring further. # Poll ingest job > Return the current state of an ingest job. Terminal states (``succeeded`` / ``failed``) remain queryable after the job completes. ``result.memories_created`` and ``result.memories_updated`` carry thin references (``{id, type, text}``); fetch ``GET /v1/memories/{id}`` for the full row. Returns ``404 job_not_found`` for unknown ids or ids belonging to a different org. ## OpenAPI ````yaml https://api.staging.xtrace.ai/openapi.public.json get /v1/memories/jobs/{job_id} openapi: 3.1.0 info: title: XTrace Vec DB description: XTrace API version: 1.0.0 servers: - url: https://api.production.xtrace.ai description: Production security: - ApiKeyHeader: [] - BearerToken: [] paths: /v1/memories/jobs/{job_id}: get: tags: - memories summary: Poll ingest job description: |- Return the current state of an ingest job. Terminal states (``succeeded`` / ``failed``) remain queryable after the job completes. ``result.memories_created`` and ``result.memories_updated`` carry thin references (``{id, type, text}``); fetch ``GET /v1/memories/{id}`` for the full row. Returns ``404 job_not_found`` for unknown ids or ids belonging to a different org. operationId: get_ingest_job_v1_memories_jobs__job_id__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/IngestJobResponse' '401': description: >- Authentication failed. Missing / invalid API key. Body carries `detail.code = "unauthorized"`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: '`detail.code = "job_not_found"` — unknown job id or tenant mismatch.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: >- Rate-limit or daily-cap exceeded. `Retry-After` and `RateLimit-*` response headers indicate when to retry. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: >- Server-side failure. Body carries `detail.code = "server_error"` with a stable error code; details are in the operator log, indexed by the `X-Request-Id` echoed in the response header. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-codeSamples: - lang: typescript label: TypeScript SDK source: > import { MemoryClient } from '@xtraceai/memory'; const client = new MemoryClient({ apiKey: process.env.XTRACE_API_KEY!, orgId: process.env.XTRACE_ORG_ID!, }); // One-shot fetch const job = await client.memories.jobs.get('job_a1b2c3d4e5f6...'); // Or poll with exponential backoff until terminal (succeeded | failed) const done = await client.memories.jobs.pollUntilDone('job_a1b2c3d4e5f6...'); console.log(done.status, done.result?.memories_created); components: schemas: IngestJobResponse: properties: object: type: string const: ingest_job title: Object description: Constant discriminator for the resource type. default: ingest_job id: type: string title: Id description: Opaque job id of the form `job_<32-hex-chars>`. examples: - job_a1b2c3d4e5f6071829304a5b6c7d8e9f status: type: string enum: - pending - running - succeeded - failed title: Status description: >- Lifecycle state. `pending` → enqueued. `running` → extraction in progress. `succeeded` → `result` is set. `failed` → `error` is set. Terminal jobs (`succeeded` / `failed`) are retained for 24h before TTL sweep returns 404 `job_not_found`. created_at: type: string format: date-time title: Created At description: ISO-8601 timestamp the job was created. updated_at: anyOf: - type: string - type: 'null' format: date-time title: Updated At description: ISO-8601 timestamp of the most recent state transition. result: anyOf: - $ref: '#/components/schemas/IngestResult' - type: 'null' description: Populated when `status = succeeded`; null otherwise. error: anyOf: - $ref: '#/components/schemas/IngestJobError' - type: 'null' description: Populated when `status = failed`; null otherwise. type: object required: - id - status - created_at title: IngestJobResponse description: |- Returned by ``POST /v1/memories`` (with status 202 by default, 200 when ``?wait=true`` succeeds inline) and by ``GET /v1/memories/jobs/{job_id}``. Same wire shape across every read of a job's lifecycle. ErrorEnvelope: properties: detail: $ref: '#/components/schemas/ErrorDetail' type: object required: - detail title: ErrorEnvelope description: |- Standard error body for non-2xx responses raised by the memory API. Pydantic field-validation failures (422) use the FastAPI- default ``HTTPValidationError`` shape instead, where ``detail`` is an array of per-field error entries — switch on the response status code to pick the right shape. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError IngestResult: properties: object: type: string const: ingest_result title: Object description: Constant discriminator for the resource type. default: ingest_result memories_created: items: $ref: '#/components/schemas/MemoryRef' type: array title: Memories Created description: >- Thin references to new facts / episodes / artifacts written this ingest. Each entry is `{id, type, text}`; full row shape is at `GET /v1/memories/{id}`. memories_updated: items: $ref: '#/components/schemas/MemoryRef' type: array title: Memories Updated description: >- Thin references to existing rows whose payload was updated during this ingest (e.g. artifact dedup hits). memories_superseded_by: additionalProperties: type: string type: object title: Memories Superseded By description: >- Map of `old_fact_id → new_fact_id`. Populated when the extraction pipeline detects a contradiction with an existing active fact: the old fact's `tag2` flips to superseded and the new fact records `supersedes = old_id`. stage_timings: additionalProperties: type: number type: object title: Stage Timings description: Per-stage extraction latencies (seconds). ignored_group_ids: items: type: string type: array title: Ignored Group Ids description: >- Subset of the request's `group_ids` that the server dropped because the id was unknown or archived. Empty on the common path. Lets clients self-correct stale caches without having to re-issue the ingest. type: object title: IngestResult description: |- Terminal job ``result`` payload, populated when status is ``succeeded``. ``memories_created`` and ``memories_updated`` carry thin :class:`MemoryRef` entries rather than full ``Memory`` rows — see :class:`MemoryRef` for the trade-off rationale and how to fetch the full row when needed. IngestJobError: properties: type: type: string title: Type description: Error class — typically `"server_error"` for ingest failures. examples: - server_error code: type: string title: Code description: >- Stable error code; switch on this rather than the message. Typically `ingest_failed`. examples: - ingest_failed message: type: string title: Message description: >- Human-readable, sanitized summary. Safe to log; not safe to switch on. type: object required: - type - code - message title: IngestJobError description: |- Job-level error payload. Mirrors the global error envelope shape so clients can branch on ``code`` the same way they do for direct request failures. ErrorDetail: properties: code: type: string title: Code description: >- Stable error identifier. Switch on this rather than parsing the message. Common values: `invalid_request`, `invalid_messages`, `memory_not_found`, `job_not_found`, `immutable_field`, `reserved_field`, `empty_text_field`, `missing_user_id`, `missing_conv_id`, `unsupported_include_option`, `cursor_mismatch`, `unauthorized`, `forbidden`, `rate_limited`, `delete_failed`, `search_failed`, `ingest_failed`, `server_error`. examples: - memory_not_found message: type: string title: Message description: Human-readable summary; safe to log but not safe to switch on. examples: - Memory 0fa1c0e6-... not found type: object required: - code - message title: ErrorDetail description: |- Inner ``detail`` block on every non-2xx response raised by a memory-API route handler. ``code`` is the stable identifier clients should switch on; ``message`` is a sanitized human- readable summary. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError MemoryRef: properties: id: type: string title: Id description: Stable UUID of the written / updated row. type: type: string enum: - fact - artifact - episode title: Type description: >- Memory subtype. Determines which detail variant lives behind the id when fetched via `GET /v1/memories/{id}`. text: type: string title: Text description: >- Short readable preview as captured at write time. Same value as ``Memory.text`` on the row at the moment of ingest. **Snapshot, not live state** — a subsequent supersede (text PATCH) replaces the row's current text; the value here keeps reflecting what the ingest job wrote. Fetch ``GET /v1/memories/{id}`` for current state. type: object required: - id - type - text title: MemoryRef description: |- Thin reference to a memory row written or updated by an ingest job. Carries only what a client needs for confirmation / per-type routing; the full ``Memory`` shape (entity ids, details, timestamps, categories) is one ``GET /v1/memories/{id}`` away. Trade-off rationale: storing the full ``Memory`` shape inside the job record duplicates content that is already persisted — every field except ``id`` is derivable via the read endpoints. The thin shape keeps the record small while preserving the two fields that make a poll response useful on its own: ``type`` (lets clients route per memory subtype without a follow-up) and ``text`` (the human-readable preview, makes the result usable as a confirmation receipt). securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: 'Long-lived org API key. Alternative: `Authorization: Bearer `.' BearerToken: type: http scheme: bearer bearerFormat: Token description: 'Long-lived API key sent as `Authorization: Bearer `.' ````