Intelligence Jobs | KINETK Graph Service API

Deep analysis runs as an async job:

POST /intelligence/jobs submits it and returns a jobId right away.
GET /intelligence/jobs/{id} polls it until it has succeeded, then returns the result.

Most jobs finish in 10–40 seconds. Not sure which job you need? See Choosing the Right Call.

`kind`	Returns	Cost
`insights`	Narratives with trajectory and sentiment, tag and theme signals, platform opportunities	0.015 credits per record analyzed
`patterns`	The visual patterns that match your question, with a written summary	10 credits per call
`stats`	Exact totals: posts, views, likes, comments and engagement, per platform	5 credits per call
`records`	Ranked posts, up to 10,000	0.01 credits per record returned

Submit

POST /intelligence/jobs
{
  "kind": "insights",
  "input": {
    "query": "sustainable sneakers",
    "window": "30d"
  }
}

cURL

curl -X POST "$API_BASE/intelligence/jobs" \
  -H "x-api-key: $API_KEY" -H "content-type: application/json" \
  -d '{ "kind": "insights", "input": { "query": "sustainable sneakers", "window": "30d" } }'

{ "jobId": "0190bd6f-…", "status": "queued", "estimated_cost": 45, "statusUrl": "/intelligence/jobs/0190bd6f-…" }

estimated_cost is the most the job can cost. Those credits are held until it finishes, and you’re charged only for what it actually used.

Two other responses are possible:

200 with fromCache: true: you ran the same job recently, so the result comes back right away. No need to poll.
202 with dedup: true: the same job is already running. Poll the jobId you got back.

Poll

GET /intelligence/jobs/0190bd6f-…

cURL

curl -H "x-api-key: $API_KEY" "$API_BASE/intelligence/jobs/0190bd6f-…"

Poll every 2–5 seconds. status goes queued → running → succeeded or failed. window: "all" and large jobs can take 1–3 minutes; allow up to 5 before treating a job as stuck.

// succeeded: the result is in `result`
{ "jobId": "…", "kind": "insights", "status": "succeeded", "result": { /* … */ } }
// failed: the held credits are fully refunded
{ "jobId": "…", "kind": "insights", "status": "failed", "error": "…" }

Large results (usually big records jobs) come back as a download link instead of result. If you see resultUrl, GET it for the full JSON. The link lasts about an hour; poll the job again for a fresh one.

Results are kept for about 24 hours. After that, polling returns 410. Store anything you need longer.

Inputs

`insights`

Field	Required	Notes
`query`	yes	Free text.
`window`	yes	`7d`, `30d`, `90d` or `all`.
`limit`	no	How many posts to analyze, up to 10,000. Defaults to 1,500 on `7d` and 3,000 on `30d`, `90d` and `all`.
`includeSignals`	no	`true` adds written takeaways for 1 credit. Needs at least 375 posts analyzed on `7d`, 750 on `30d` or `90d`, or 1,500 on `all`; otherwise the job fails and is fully refunded.
`returnRecords`	no	Also return the top N evidence posts. Default `0`.
`includeGraphs`	no	Adds relationship graphs. Default `false`; makes the response much larger.
`platforms`	no	Defaults to all.

Each narrative in an insights result includes:

label, summary, topTags and representativeContent[] (its top 8 posts).
corpusEvidence: how big the narrative is across the whole corpus, not just your results, and whether it’s growing.
persistentLink.narrativeId: pass it to GET /narratives/{id} to follow the narrative over time.

`patterns`

Field	Required	Notes
`query`	yes	Free text.
`limit`	no	Patterns to return. Default 8, max 25.
`includeProse`	no	Default `true`. `false` skips the written summary.

No window. See Pattern Intelligence.

`stats`

Field	Required	Notes
`query`	yes	Free text.
`window`	no	`all` (default), `90d`, `30d`, `7d` or `24h`.
`platforms`	no	Defaults to all.

Returns { query, window, total, platforms[] }, an exact count over everything that matches.

`records`

Field	Required	Notes
`query`	yes	Free text. Hashtags (`#fitness`) also widen the match by tag.
`window`	yes	`7d`, `30d`, `90d` or `all`.
`limit`	yes	How many posts to return, 100–10,000. `1000` is a good start.
`platforms`	no	Any of `tiktok`, `instagram`, `reddit`, `pinterest`, `x`, `snapchat`. Defaults to all.

Each post is a content object.

Through the MCP

In an AI assistant, the hosted MCP’s kinetk_get_context tool submits a job and waits for the result in one step. See What You Can Ask.