Getting results

POST /v1/messages returns within about 30 seconds. If the agent finished in that time, you already have the result. If it started longer work, the message is processing and you follow it until it's final.

There are three ways to follow a message. Use whichever fits your stack:

They all read the same record, so they never disagree.

#Long-poll the message

curl "https://api.supercool.com/v1/messages/msg_3f9a1c2e7b8d4e5f6a7b8c9d?wait=30" \
  -H "Authorization: Bearer $SUPERCOOL_API_KEY"

wait holds the request for up to that many seconds (0 to 45) and returns as soon as something changes: the status, the agent's reply arriving, or any job's status. It also returns right away when the message is already final. Without wait, you get the current state immediately.

import os
import requests

API = "https://api.supercool.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SUPERCOOL_API_KEY']}"}

def wait_for(message_id):
    while True:
        r = requests.get(f"{API}/messages/{message_id}", headers=HEADERS, params={"wait": 30}, timeout=60)
        r.raise_for_status()
        msg = r.json()
        if msg["final"] or msg.get("resume") == "add_credits":
            return msg

Set your HTTP client's timeout above wait (60 seconds for wait=30 is a good default). Long-polls count toward a limit of 1,500 waits per hour per account, which a loop like this stays well under.

#The message object

The full schema is in the reference.

#Statuses

A message's status sums up all of its work. It is not just "has the agent replied": the agent often replies in seconds ("On it") while the video it started takes minutes.

Rely on final, not on the status alone. A blocked or partial message whose queued work is waiting for credits is not final yet: it can still move to processing and then completed.

#How the status is worked out

The status comes from structured signals: the agent's actions and each job's outcome, never from the wording of the reply. The rules apply in this order, and the first match wins:

1. The agent is still planning or starting work: processing. A quick job finishing while the agent sets up the next one can't end the message early.
2. The agent's turn failed, or the agent was busy with another message: failed, even if some jobs finished.
3. Any job is running: processing.
4. The agent asked a question and nothing is running: needs_input.
5. No jobs, just a reply: completed.
6. Every job completed: completed.
7. Every job blocked: blocked.
8. Every job expired: expired.
9. At least one job completed and at least one didn't: partial.
10. Otherwise: failed.

So if a message asked for two things and the second was refused for lack of credits, it ends partial, with one completed job and one blocked job.

#Reasons

reason says why a message or job didn't simply complete. For a message, it's the reason of the first job that explains the status.

Treat unknown reasons like failed: new, more specific reasons may be added.

#Jobs

Each job is one piece of work: one run in one chat. A message that asked for a video and a landing page usually has two jobs.

#Waiting for credits

If work was queued but your account had no credits, the job is blocked with reason: "out_of_credits", queued: true and final: false. The message then carries:

{
  "status": "blocked",
  "reason": "out_of_credits",
  "final": false,
  "resume": "add_credits",
  "resume_by": "2026-10-01T14:02:11.402000Z"
}

Add credits before resume_by (24 hours after the work was queued) and the work starts by itself (once fewer than 5 jobs are running on your account). The job moves to running and then to its result, and the message follows (blocked → processing → completed). Don't resend the message, or you'll start the work twice. After resume_by, the job becomes expired with queue_expired, and you have to send the message again.

#Events

GET /v1/messages/{id}/events returns the message's update log: what happened, in order. It holds only this message's entries, plus those of any work it joined as a follow-up (so a follow-up sees that work's progress and result). If another message works separately in the same chat, its progress and results don't show up here. Use it to show progress ("Rendering the video…"), or to process each job's result as it lands.

curl "https://api.supercool.com/v1/messages/msg_3f9a1c2e7b8d4e5f6a7b8c9d/events?wait=30" \
  -H "Authorization: Bearer $SUPERCOOL_API_KEY"

{
  "object": "list",
  "data": [
    { "seq": 117, "type": "agent_reply", "message_id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d", "text": "On it…", "files": [], "delivered_sync": true, "at": "2026-09-30T14:02:12.000000Z" },
    { "seq": 118, "type": "progress", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "step": "Rendering the video", "status": "started", "file_names": [], "at": "2026-09-30T14:03:02.000000Z" },
    { "seq": 121, "type": "result", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "title": "Candle shop vertical ad", "text": "Your 15 second ad is ready.", "outcome": "completed", "files": [], "at": "2026-09-30T14:06:40.000000Z" }
  ],
  "has_more": false,
  "done": true,
  "cursor": "eyJjIjoiYXBpOnU..."
}

• Pass cursor from the previous page to get only new entries. With no cursor, the log starts where the message started.
• wait (0 to 45) holds the call until there's something new. It always waits at least one second.
• has_more: true means more entries are ready: call again right away.
• done: true means the message has nothing more to report.
• Only one wait per message runs at a time. A second concurrent call gets 409 poll_in_progress.
• Entries are kept for 7 days. An older cursor gets cursor_expired: true and a fresh cursor. Read the message itself to catch up.

Every entry has seq, type, at and, when known, work_id, message_id and job_id. Progress and result entries carry message_id and job_id whenever the job is known.

#Webhooks

Rather than polling, register a URL and SuperCool POSTs a signed event when a job changes and when the message reaches a status other than processing. See Webhooks.

#Recover old work

A message or job is expired when its work didn't report back in time (7 days for running work). The work may still have finished. POST /v1/messages/{id}/recover looks for its result again. It never resends the message or starts new work.

curl -X POST https://api.supercool.com/v1/messages/msg_3f9a1c2e7b8d4e5f6a7b8c9d/recover \
  -H "Authorization: Bearer $SUPERCOOL_API_KEY"

{
  "id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d",
  "object": "recovery",
  "work": [{ "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "state": "recovering" }]
}

Each piece of work comes back settled (it already has its outcome), watching (still being watched), recovering (being looked up again: follow the message as usual) or exhausted (recovered too many times). For exhausted work, read the chat with GET /v1/work/{work_id}.

#How long messages are kept

A message, its jobs and its results stay readable for at least 14 days after its last job's deadline. For running work the deadline is 7 days after it started; for queued work, 24 hours after it was queued; a plain reply is kept 14 days. After that, GET /v1/messages/{id} returns 404 not_found.

The work itself lasts as long as the chat exists in your account: read it any time with GET /v1/work/{work_id}, and get fresh file links from GET /v1/files/{file_id}.