Skip to navigation

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. charged is the full rate, except for a patterns/stats answer this account already paid for today, which is 0.
  • 202 + { dedup: true } — identical job currently queued/running; reuses the in-flight jobId.
  • 202 + { estimated_cost } — new job accepted; the credits were reserved at the estimate. Poll GET /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

x-api-keystring

Customer secret key, required on every request. Validated natively by API Gateway; missing / invalid / revoked → 403.

Request

This endpoint expects an object.
insightsobjectRequired
OR
recordsobjectRequired
OR
patternsobjectRequired
OR
statsobjectRequired

Response headers

X-Kinetk-Credits-Useddouble

Credits consumed by this call (reserved estimate on a 202; actual once settled).

X-Kinetk-Credits-Remainingdouble
Account credit balance remaining after this call.

Response

Successful response
jobIdstring
statusenum
Allowed values:
dedupbooleanOptional
estimated_costdoubleOptional

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.

fromCachebooleanOptional
resultobjectOptional
resultBytesdoubleOptional

Size of the stored result in bytes (present alongside resultUrl).

resultExpiresAtstringOptional

ISO-8601 expiry of resultUrl (clamped to the job’s own retention).

resultStorageenumOptional

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).

Allowed values:
resultUrlstringOptional

Short-lived presigned GET URL for a large result (present iff resultStorage === “s3”).

statusUrlstringOptional

Errors

402
Payment Required Error