# Jobs and resumable polling

> Persist asynchronous job IDs, poll with bounded backoff, and stop on every terminal status.

Canonical guide: <https://engine.neraperla.com/docs/jobs>

Raw Markdown: <https://engine.neraperla.com/docs/raw/jobs.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

[Infinite Intent](https://engine.neraperla.com/docs/infinite-intent) also uses `GET /v1/jobs/{job_id}`,
with type `infinite_intent`. Open `result.report_url` in a new browser tab.
Its `billing` fields report actual charge and credits used.

Playbooks, Audiences, Brand research, Prospecting, Documents, Message Templates, Site Intelligence, and Enrichment batches return asynchronous jobs. The shared `type` field selects the typed `input` and `result`: `playbooks` uses `PublicPlaybookJobResponse`, `audiences` uses `PublicAudienceJobResponse`, `brands` uses `PublicBrandJobResponse`, `prospecting` uses `ProspectingJobResponse`, `documents` uses `DocumentJobResponse`, `message_templates` uses `MessageTemplateJobResponse`, `site_intelligence` uses `PublicSiteIntelligenceJobResponse`, `enrichment` uses `PublicEnrichmentJobResponse`, and `infinite_intent` uses `InfiniteIntentJobResponse`.

## Lifecycle

| Status | Terminal | Client behavior |
|---|---:|---|
| `queued` | No | Wait before polling again. |
| `running` | No | Report `progress` if useful and keep polling. |
| `succeeded` | Yes | Validate and render the typed `result`. |
| `failed` | Yes | Stop and handle `error_code` when present, then surface the job's `error` message. |
| `canceled` | Yes | Stop. Runs are canceled from the web console; the API has no cancel operation except Infinite Intent's. |

Do not wait only for `succeeded`, because that creates infinite loops after failures or cancellation.

## Typical durations

Generation jobs run for minutes, not seconds. In current production operation, Playbooks jobs typically complete in about 10–20 minutes and Prospecting runs typically take several minutes; Audiences jobs can run substantially longer depending on scope. These are operational observations to size polling intervals and client deadlines, not completion-time promises.

## Resumable polling algorithm

1. After a successful create response, persist `id` before the first poll.
2. Poll `GET /v1/jobs/{job_id}` after 2 seconds.
3. Back off exponentially with jitter, capped at 10 seconds. For capabilities that typically run for many minutes, such as Playbooks, settle at a steady 15–30 second interval — polling faster does not make the job finish sooner.
4. Set a local deadline appropriate to the caller and generous relative to the typical duration above. A deadline stops the client, not server work.
5. Keep the ID when the deadline expires and resume it later rather than creating duplicate work.
6. Stop on `succeeded`, `failed`, or `canceled`.

Before the create request, persist an `Idempotency-Key`. If the connection fails before the response arrives, repeat the exact job-creation operation and input with that key during its 24-hour replay window. This recovers the original response instead of creating duplicate work.

The [Quickstart](https://engine.neraperla.com/docs/getting-started) includes a complete cURL implementation. Tested Python and TypeScript implementations under `docs/examples` add jitter and use the same terminal-state rules.

## Ownership and billing

A project key sees only its own project's jobs. A company-level key reads any job of your company: without a `Blackpearl-Project` header the job's own project is used, and with one the job must belong to that project. A missing or cross-project ID returns `not_found`. Jobs in an archived project stay readable by id to a company-level key that sends no `Blackpearl-Project` header, so a run in progress when the project was archived can still be polled to its end. Creating a job records accepted work and its eventual capability usage. Poll requests are subject to request rate limits but are not billed as new generation requests.

Job creation requires a positive spendable credit balance, but does not quote the run's price; for a typical price before you submit, see [Billing](https://engine.neraperla.com/docs/billing). A project with an allowance also needs enough of it left to start a run; see [Projects](https://engine.neraperla.com/docs/projects). The run is priced and charged when it finishes, and `usage.cost_usd` reports that charge: `0` while the run is in progress and for a failed run, the full price (including any data-record fee) for a succeeded run, and the charge for the work done before the cancel for a canceled run (`0` for a prospecting run canceled before its search started). Most canceled runs stop within seconds and their charge follows. A canceled Playbooks run is the exception: its generation keeps running, and it is charged in full when the generation finishes. Until a canceled run's charge is recorded, `usage.cost_usd` reads `0`: read the job again later, or find the charge in `GET /v1/charges`. If the charge exceeds the remaining balance, the full amount is still charged and the job succeeds with its result: the balance goes negative, configured auto recharge is triggered, and new jobs are rejected with `insufficient_credits` until a top-up restores a positive balance.

`progress` is coarse and is not a completion-time promise. Do not build an SLA from it. Timestamps (`created_at`, `started_at`, `finished_at`, `expires_at`) are ISO-8601 UTC ending in `Z`. Every public job includes `expires_at`, exactly 30 days after `created_at`. Job metadata, input, and results remain readable through that timestamp. Store any result your application needs longer.

After `expires_at`, direct job and Audience candidate reads return `410` with `error.code` `job_expired`. Cleanup removes retained input, result, failure detail, stages, and private diagnostics, but preserves the minimal ownership tombstone plus usage, charge, credit, and audit records. Expiry does not cancel work, reverse billed usage, or erase accounting history.

## Poll errors

Safe GET requests may be retried for `rate_limit_exceeded` after `Retry-After` and for documented transient `5xx` failures with bounded exponential backoff. Fix authentication, entitlement, quota, and budget errors before retrying. See [Errors](https://engine.neraperla.com/docs/errors).

Over a run lasting many minutes, an individual poll can also fail in transit — a connection error, a timeout, or a `502`, `503`, or `504` produced by network infrastructure between your application and the platform (CDN edge, load balancers, or an outbound proxy on your side) — while the job continues normally on the platform. Treat any such failure as retryable: retry the same `GET /v1/jobs/{job_id}` with bounded backoff, and never conclude that the job failed or create a replacement job because one poll did not succeed. The job's `status` in a successful response is the only authoritative signal, and the result remains retrievable until `expires_at` even if your poller stops for an extended period.

Job retrieval is OpenAPI operation `get_job_v1_jobs__job_id__get`. Its response is the same `type`-discriminated union of the Job schemas listed at the top of this page. Documents results contain file references; download their bytes through the authenticated endpoint documented in [Documents](https://engine.neraperla.com/docs/documents) before the Job expires.
