Jobs and resumable polling
Persist asynchronous job IDs, poll with bounded backoff, and stop on every terminal status.
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#
- After a successful create response, persist
idbefore the first poll. - Poll
GET /v1/jobs/{job_id}after 2 seconds. - 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.
- Set a local deadline appropriate to the caller and generous relative to the typical duration above. A deadline stops the client, not server work.
- Keep the ID when the deadline expires and resume it later rather than creating duplicate work.
- Stop on
succeeded,failed, orcanceled.
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 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. A project with an allowance also needs enough of it left to start a run; see 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.
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 before the Job expires.