Get Started

Quickstart

Five minutes from curl to a real insights result. Pick any HTTP client you like; we use curl here.

Prerequisites

$export API_BASE="https://api.kinetk.ai/graph"
$export API_KEY="<paste your key here>"

If you don’t have a key yet, see Authentication. The production base URL is https://api.kinetk.ai/graph — see Introduction.

1. Health check

$curl -H "x-api-key: $API_KEY" "$API_BASE/health"

Expected response (status 200, latency under 1 second):

1{
2  "ok": true,
3  "lastSyncedAt": "2026-04-28T17:32:11.000Z",
4  "syncFreshSeconds": 1432
5}

syncFreshSeconds tells you how recently the ingestion pipeline ran. Under 3600 (one hour) means data is fresh. Much higher and the hourly sync is lagging — see Sync & Freshness.

If you get 403 { "message": "Forbidden" }, the API key isn’t being sent — check the header name and value.

2. Submit an async intelligence job

Both the records and insights kinds run async because they can take 5–20 seconds. Submit returns immediately with a jobId:

$curl -X POST "$API_BASE/intelligence/jobs" \
>  -H "x-api-key: $API_KEY" \
>  -H "content-type: application/json" \
>  -d '{
>    "kind": "insights",
>    "input": {
>      "query": "smart watch launch",
>      "window: "7d",
>      "limit: 3000
>    }
>  }'

insights takes query (required) plus an optional includeIntelligenceSignals boolean; everything else (time window, scan size, platforms) is managed by the service for this kind, and any other field returns 400. The records kind accepts filters and requires an explicit window and limit — see Intelligence Jobs.

Three possible responses:

1// Fresh submit — new work queued, credits reserved at the estimate:
2{ "jobId": "0190bd6f-...", "status": "queued", "estimated_cost": 0.5, "statusUrl": "/intelligence/jobs/0190bd6f-..." }
3
4// Cache hit — identical input within freshness window, inline result:
5{ "jobId": "0190bd6f-...", "status": "succeeded", "result": { /* full payload */ }, "fromCache": true }
6
7// Dedup — identical input already running, same jobId returned:
8{ "jobId": "0190bd6f-...", "status": "queued", "dedup": true, "statusUrl": "/intelligence/jobs/0190bd6f-..." }

Save the jobId:

$JOB="0190bd6f-..."

3. Poll for the result

$curl -H "x-api-key: $API_KEY" "$API_BASE/intelligence/jobs/$JOB"

Poll every 2–5 seconds until status flips from queued → running → succeeded. Typical end-to-end time for insights: 5–20 seconds.

1// While running:
2{ "jobId": "0190bd6f-...", "kind": "insights", "status": "running", "submittedAt": 1745859300000, "startedAt": 1745859302100 }
3
4// When done:
5{
6  "jobId": "0190bd6f-...",
7  "kind": "insights",
8  "status": "succeeded",
9  "submittedAt": 1745859300000,
10  "startedAt":   1745859302100,
11  "completedAt": 1745859315400,
12  "result": { /* signals payload — see API reference */ }
13}

4. Skip the polling — use the MCP

If you’d rather have Claude or Cursor handle the submit/poll loop for you, install the kinetk MCP server — see MCP Installation. The MCP exposes the same insights flow as a one-tool call with built-in polling and a slim, token-efficient response envelope.

Coming soon

The trending narratives endpoints and full documentation are on the way. Check back shortly.

Next steps