Job lifecycle

Inference and internalization are asynchronous jobs. The submission response is a receipt for durable work, not the final result. Your application can disconnect after saving the job ID and resume observation later.

AdmissionCopy Anchor Link

Before creating a job, the platform authenticates the key, checks its scope, validates the body, and looks for an existing operation with the same idempotency key. For new work it resolves the subject's active adapter and verifies that available credits and the monthly limit cover the reservation.

The job, its adapter snapshot, the idempotency claim, and its credit reservation are recorded together. Concurrent submissions cannot spend the same available credit. An invalid or unfunded request does not create an accepted job that your application should poll.

Execution statesCopy Anchor Link

queued → running → succeeded     inference result
                 → ready         validated learning candidate
                 → rejected      learning gate did not pass
                 → failed        known terminal error
                 → reconciliation_required

Some failures occur before execution starts, so clients should not require every intermediate state to appear. Polling can also skip short-lived transitions. Treat the latest job record as authoritative.

phase provides additional diagnostic context, such as dispatch or a worker operation. It is not a progress percentage or a stable list of steps to build a rigid UI around. Use status for application decisions and show phase as supplementary detail.

Completion and settlementCopy Anchor Link

A known terminal outcome settles the reservation once. Inference charges use measured input and output tokens. Internalizations use measured teacher, scoring, evaluation, and training tokens, plus verified initial hosting for a saved candidate. The price version is fixed at admission. Unused reserved credit becomes available again.

Read billing.settled alongside status. Zero usage while a job is running does not prove no work has happened. A reservation is not a final charge, and the original reserved amount remains in the completed job for audit purposes.

On success, inference returns result.text. Internalization returns candidate, validation, and activation metadata. A rejected candidate does not replace the active adapter. A ready candidate can be saved without becoming active, so applications must inspect result.activated before promising that future requests use it.

Ambiguous outcomesCopy Anchor Link

reconciliation_required means the platform cannot safely establish the provider outcome or complete usage. Examples include a lost worker lease after paid work may have started, an unconfirmed dispatch, or incomplete usage evidence.

The reservation stays held. Do not convert this state to a normal failure and automatically submit a new operation. An operator must examine execution receipts and settle the known outcome without replaying paid work. The same job can later become terminal after reconciliation.

Client timeoutsCopy Anchor Link

A client deadline, polling timeout, closed browser, or aborted HTTP read does not cancel a job. Resume by reading the saved ID. If the submission response was lost, repeat admission with the same idempotency key and unchanged payload to recover the original receipt.

No public cancellation endpoint or customer webhook exists yet. Use bounded polling or a durable application task that periodically reads the job. See Polling and recovery for the client pattern and Job reference for every response field.