Coding pipeline

POST /v1/code is the hero endpoint. This page covers what it actually does under the hood so you can predict latency, plan around quotas, and choose between sync and async.

The one-call flow

For every request, the pipeline runs four stages:

1. Ingest — verbatims are deduplicated, trimmed, and pre-filtered for empty/junk values. (Heavy noise removal is your responsibility — see NO_DATA for the threshold.)
2. Codebook — if you didn’t pass an existing codebook, the API generates one from a sample of your responses. You can override this with the codebook field on the request.
3. Coding — each remaining verbatim is sent to the LLM with the codebook. Each verbatim is one coded response and costs 1 credit.
4. Review — competing-aspect responses get a needs_review: true flag and a review_reason string. The model can also flag inconsistencies, which you can query through refinement suggestions.

Sync vs async — the 50-response threshold

Responses in request	HTTP status	What you get back
< 50	200 OK	The full coded result inline. Typical latency: 5-20s.
≥ 50	202 Accepted	A job_id. Poll GET /v1/jobs/{id} or register a webhook.

The threshold is fixed — you can’t force one mode or the other on /v1/code. If you want sync semantics for a larger payload, split it into batches of 49 and reconcile codebooks downstream (or pre-generate the codebook once and pass it on every batch).

Note

Polling cadence: jobs almost always complete in (n / 20) seconds (e.g. 1,000 responses ≈ 50s). Polling every 2-5 seconds is plenty. Use the Retry-After header on the job response when present.

Reusing a codebook

Generating a codebook is the slowest part of any first run. For repeated waves, generate it once and pass it on subsequent calls:

POST /v1/code
{
  "question": "Why did you choose this brand?",
  "codebook": [
    { "code": "Stain removal", "category": "Reason" },
    { "code": "Scent", "category": "Reason" },
    { "code": "Value / pack size", "category": "Reason" }
  ],
  "responses": ["..."]
}

When codebook is provided, the pipeline skips stage 2 entirely. New themes that don’t fit existing codes are surfaced as suggestions rather than added silently — apply them via the refinement endpoints.

Job lifecycle

queued -> processing -> completed
                    \-> failed

• queued — request accepted, waiting for a worker.
• processing — a worker has picked it up.
• completed — data.result contains the coded data.
• failed — data.error contains a structured error — common ones are CODING_FAILED and CODEBOOK_GENERATION_FAILED.

Jobs are retained for 7 days, then garbage collected.

Credits at a glance

• One coded response = one credit.
• Codebook generation is free.
• A failed job (status failed before any verbatims were coded) does not charge credits.
• A job that partially completes charges only for the verbatims that were successfully coded.

See Credits for balance, plans, and what happens when you hit zero.

Errors during the pipeline

Stage failures map to specific error codes:

Stage	Likely error
Ingest	VALIDATION_ERROR, NO_DATA
Codebook	CODEBOOK_GENERATION_FAILED, EMPTY_CODEBOOK
Coding	CODING_FAILED, GATEWAY_TIMEOUT
Queue	QUEUE_UNAVAILABLE, JOB_ALREADY_RUNNING