> This page is for version v1.0.1 (default). > For other versions, use one of these documentation indexes: > - v1.0.1 (default): https://docs.kinetk.ai/v-1-0-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kinetk.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kinetk.ai/_mcp/server. # Intelligence Jobs > Submit a job, poll it, read the result. Inputs for records, insights, patterns and stats. Deep analysis runs as an async job: 1. `POST /intelligence/jobs` submits it and returns a `jobId` right away. 2. `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](/documentation/guides/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 ```http POST /intelligence/jobs { "kind": "insights", "input": { "query": "sustainable sneakers", "window": "30d" } } ``` #### cURL ```bash 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" } }' ``` ```json { "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 ```http GET /intelligence/jobs/0190bd6f-… ``` #### cURL ```bash 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. ```jsonc // 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}`](/documentation/guides/narrative-intelligence#one-narrative) 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](/documentation/guides/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](/documentation/guides/the-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](/documentation/mcp-server/what-you-can-ask).