Guides

Queued jobs

Two Tools take longer than an HTTP request should. They queue the work, return a job id immediately, and expose the result through get_job.

2 async toolsPoll get_job

Which Tools queue

Tool	Why it queues	Price
`analyze_post`	Use to examine a TikTok, Instagram or YouTube video post's hook, timeline, transcript and reusable structure. Cost: 10 + 4 per started 30 seconds (14–34 credits). Videos up to 180 seconds. Results may contain unknowns where evidence is insufficient.	10 + 4 credits per started 30 seconds (14–34)
`list_patterns`	Use to find recurring hooks and formats among standout posts by creators tracked in this workspace. Returns evidence posts and ways to adapt each pattern. Requires at least three saved standout posts.	20 credits

An async Tool has no separate endpoint: call it exactly like a synchronous Tool. The difference is the response shape, not the URL.

Submit the work

The call returns as soon as the job is accepted. Credits are held at this point; the work itself continues when a worker picks it up.

POST /openapi/v1/tools/analyze_post

curl -X POST https://api.cuekoo.com/openapi/v1/tools/analyze_post \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@creator/video/7412345678901234567"}'

{
  "job_id": "0190f3c2-7f1a-7c3e-9d21-6a0e5b8f2c11",
  "status": "queued"
}

The job id is a UUID. Store it: it is the only handle for the result, and get_job requires it.

Poll get_job

get_job is a free, synchronous Tool. Poll it until status is succeeded or failed.

POST /openapi/v1/tools/get_job

curl -X POST https://api.cuekoo.com/openapi/v1/tools/get_job \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "0190f3c2-7f1a-7c3e-9d21-6a0e5b8f2c11"}'

{
  "id": "0190f3c2-7f1a-7c3e-9d21-6a0e5b8f2c11",
  "tool": "analyze_post",
  "status": "succeeded",
  "result": { "post": { "id": "7412345678901234567" } },
  "created_at": "2026-11-08T09:41:02Z",
  "finished_at": "2026-11-08T09:41:39Z"
}

Status	Meaning
`queued`	Accepted and waiting for a worker.
`running`	A worker is executing the Tool.
`succeeded`	The result is in the result field.
`failed`	error_code and error explain the failure; nothing was charged.

Polling without waste

Start with a 2-second interval and back off to 30 seconds for long videos. There is no webhook for job completion on the documented surface, so polling is the only way to learn the outcome.

Do not poll faster than once per second.
Stop polling on succeeded or failed.
A 410 with job_expired means the result is no longer stored. Submit the work again if you still need it.

What it costs

An async Tool holds its maximum price at submit and settles on completion, exactly like a synchronous paid Tool. A failed job releases the hold and charges nothing. The hold expires after 2 hours if no worker settles it.

Full pricing, including analyze_post's per-length component, is on Credits. Async-specific error codes are on Errors.