---
title: "Inspect one project-scoped Formation job"
method: GET
path: "/v1/formation/jobs/{job_id}"
tags: ["memory"]
---

# Inspect one project-scoped Formation job

`GET /v1/formation/jobs/{job_id}`

## Request

- Base URL: `https://api.contextdb.ai`
- URL: `https://api.contextdb.ai/v1/formation/jobs/{job_id}`
- Auth: HTTP bearer

## Path parameters

- `job_id` string, required

## Response `200`

Current state, attempts, and encrypted-at-rest terminal result

- FormationJob
  - `job_id` string, required
  - `status` 'queued' | 'running' | 'retry_wait' | 'succeeded' | 'failed', required
  - `mode` 'propose' | 'commit', required
  - `attempt_count` integer, required
  - `provider_attempts` integer, required
  - `max_attempts` integer, required
  - `max_provider_attempts` integer, required
  - `terminal_reason` 'completed' | 'no_memories' | 'input_rejected' | 'pii_rejected' | 'scope_rejected' | 'result_rejected' | 'provider_unavailable' | 'provider_error' | 'deadline_exceeded' | 'max_attempts' | 'worker_lost' | 'commit_rejected' | 'storage_error' | 'internal_error' | 'configuration_changed', required
  - `error_code` string, nullable, required
  - `accepted_count` integer, required
  - `rejected_count` integer, required
  - `provider` string, required
  - `model` string, required
  - `provider_latency_ms` integer, required
  - `provider_cost_usd` number, nullable, required
  - `elapsed_ms` integer, required
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable, required
  - `completed_at` string, date-time, nullable, required
  - `attempts` FormationAttempt[], required
    - `attempt` integer, required
    - `status` 'running' | 'succeeded' | 'retry' | 'failed' | 'worker_lost' | 'deadline_exceeded', required
    - `provider_called` boolean, required
    - `provider` string, required
    - `model` string, required
    - `latency_ms` integer, required
    - `accepted_count` integer, required
    - `rejected_count` integer, required
    - `provider_cost_usd` number, nullable, required
    - `error_code` string, nullable, required
    - `failure_reason` string, nullable, required
    - `started_at` string, date-time, required
    - `finished_at` string, date-time, nullable, required
  - `result` FormationJobResult, required
    - `mode` 'propose' | 'commit', required
    - `terminal_reason` 'completed' | 'no_memories' | 'input_rejected' | 'pii_rejected' | 'scope_rejected' | 'result_rejected' | 'provider_unavailable' | 'provider_error' | 'deadline_exceeded' | 'max_attempts' | 'worker_lost' | 'commit_rejected' | 'storage_error' | 'internal_error' | 'configuration_changed', required
    - `candidates` FormationCandidateReview[], required
      - `content` string, nullable, required
      - `quote` string, nullable, required: Exact PII-processed quote supporting an accepted candidate
      - `turn_indexes` integer[], required
      - `source` 'user_stated' | 'agent_inferred' | 'third_party', required: Who vouches for the claim. Required on writes.
      - `confidence` number, nullable, required
      - `action_relevant` boolean, nullable, required
      - `entity` string, nullable, required
      - `attribute` string, nullable, required
      - `operation` 'add' | 'update' | 'delete' | 'noop', required
      - `target_memory_id` string, nullable, required
      - `noop_reason` string, nullable, required
      - `candidate_key` string, nullable, required
      - `accepted` boolean, required
      - `candidate_index` integer
      - `rejection_reason` string, nullable, required
    - `memory_ids` string[], required
    - `operation_results` FormationOperationResult[], required
      - `candidate_key` string, required
      - `requested_operation` 'add' | 'update' | 'delete' | 'noop', required
      - `applied_operation` 'add' | 'update' | 'delete' | 'noop', required
      - `outcome` 'added' | 'updated' | 'deleted' | 'noop' | 'contested', required
      - `memory_id` string, nullable, required
      - `previous_memory_ids` string[], required
      - `deleted_memory_ids` string[], required
      - `target_memory_id` string, nullable, required
      - `noop_reason` string, nullable, required
    - `operation_counts` FormationOperationCounts, required
      - `added` integer, required
      - `updated` integer, required
      - `deleted` integer, required
      - `noop` integer, required
    - `memory_version` integer, nullable, required
    - `primary_wal_lsn` string, nullable, required
    - `accepted_count` integer, required
    - `rejected_count` integer, required
    - `provider` string, required
    - `model` string, required
    - `turns` integer, required
    - `provider_attempts` integer, required
    - `provider_latency_ms` integer, required
    - `provider_cost_usd` number, nullable, required
    - `error_code` string, nullable, required
  - `request_id` string, required

## Other responses

- `401`: Missing, malformed, unknown, or revoked API key
- `403`: Authenticated but not allowed (entitlement or billing state)
- `404`: Target not found in the caller's partition (or missing)
- `429`: The client IP/project exceeded its request rate, or the project's idempotency retention capacity is full until older keys expire.
- `503`: Memory or metadata store unreachable

---

[API](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api.md) · [All operations](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/revisions/9e441d2e21a7?raw)