Submit an async intelligence job
Submit a job for async execution. Request body is { kind, input }
discriminated by kind.
Use kind: stats for exact engagement totals over every record matching
the query. Matches come from indexed tags, text, themes and products plus
semantically similar content; the semantic matches help find the right
terms but never cap the count, though semantic discovery is bounded, so a
very large topic can return a floor rather than the full population.
Incomplete discovery or reconciliation fails the job instead of returning
sampled or partial totals. Stats jobs cost a flat $5.00 per
call, expose 24h publicly, and may omit window (defaults to all).
Response shapes:
200 + { fromCache: true, result, charged }— identical recent job within the per-kind freshness window; cached result returned synchronously.chargedis the full rate, except for apatterns/statsanswer this account already paid for today, which is0.202 + { dedup: true }— identical job currently queued/running; reuses the in-flightjobId.202 + { estimated_cost }— new job accepted; the credits were reserved at the estimate. PollGET /intelligence/jobs/{id}.402— insufficient credits; body recommends how to fit your budget.
For the per-record-charged kinds, window (in input) is REQUIRED — it
selects the slice of the corpus to retrieve over. It does NOT affect price.
estimated_cost is an upper bound for those kinds; the final charge is
computed from the records actually returned.
Input validation is strict: any undeclared field, type mismatch, or
out-of-enum value is rejected with 400 (nothing is silently stripped or
coerced).
Authentication
Customer secret key, required on every request. Validated natively by API Gateway; missing / invalid / revoked → 403.
Request
Response headers
Credits consumed by this call (reserved estimate on a 202; actual once settled).
Response
Upper-bound credit estimate for this run, priced on the (possibly server-derived) analysis depth + the includeSignals add-on. This is the HOLD placed on billed keys; settlement bills the records actually analyzed and refunds the difference. Informational (never charged) for internal/admin keys.
Size of the stored result in bytes (present alongside resultUrl).
ISO-8601 expiry of resultUrl (clamped to the job’s own retention).
Set to “s3” when the result was too large to return inline; in that case
result is omitted and resultUrl holds a short-lived presigned download
URL instead. Fetch the URL directly; re-poll for a fresh one after it
expires (see resultExpiresAt).
Short-lived presigned GET URL for a large result (present iff resultStorage === “s3”).