> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/api-and-mcp-concepts/async-jobs-and-polling.md).

# Async jobs and polling

Track accepted jobs using operation-specific IDs, polling intervals, error fields, and terminal states.

Publishing, source extraction, visual generation, comment posting, and message sending finish after the initial request. Save the returned ID and check the operation's status before reporting success.

## Completion rules

| Operation      | Status lookup                                                      | Completion                                                                                                                     |
| -------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Immediate post | `blotato_get_post_status` or `GET /v2/posts/:postSubmissionId`     | `published` succeeds. `failed` stops the workflow. `in-progress` needs another check.                                          |
| Scheduled post | Create response, then schedule lookup when needed                  | Report the returned `scheduledTime`. `scheduled` means scheduled, rather than published.                                       |
| Source         | `blotato_get_source_status` or `GET /v2/source-resolutions-v3/:id` | `completed` succeeds. `failed` stops the workflow. `queued` and `processing` need another check.                               |
| Visual         | `blotato_get_design_status` or `GET /v2/videos/creations/:id`      | `item.status: done` supplies finished media. Stop on `item.error`, `creation-from-template-failed`, or `insufficient-credits`. |
| Comment        | `blotato_get_comment` or `GET /v2/comments/:commentId`             | `posted` succeeds. `failed` stops the workflow.                                                                                |
| Message        | `blotato_get_message` or `GET /v2/messages/:messageId`             | `sent` succeeds. `failed` stops the workflow.                                                                                  |

## MCP timing

`blotato_create_post` waits internally for up to 20 seconds for immediate publishing. `blotato_create_source` also waits internally for up to 20 seconds. If either returns unfinished work, use its status tool with the same ID.

1. Wait at least 10 seconds between post or source status calls.
2. Wait at least 15 seconds between visual status calls.
3. For queued comments and messages, space status checks to stay within the [endpoint rate limits](/api-and-mcp-concepts/rate-limits.md).
4. When the agent's execution window ends, retain the ID and report processing status. Resume with a status lookup rather than another create request.

Inspect both MCP `isError` and the operation's status. A post or source status lookup returning `failed` is still a failed job even when the tool call itself succeeded. Source status failures use `message`. Post status failures use `errorMessage`.

Post `in-progress` is a fallback when no matching result record is found, not an independent queue-health check. Verify the saved submission ID and use a bounded polling loop. See [post lifecycle](/api-and-mcp-concepts/post-lifecycle.md#look-up-existing-work).

## REST timing

REST create calls return a submission or creation response. The caller manages status checks. Use the intervals above as polling guidance and respect any rate-limit response. A `201` response confirms acceptance, rather than downstream publication.

## Visual states

Visual generation uses `queueing`, `generating-script`, `script-ready`, `generating-media`, `media-ready`, and `exporting` before `done`. Not every template traverses every state.

Inspect `item.error` on every response. A visual with an error has stopped even if its status remains `script-ready` or another intermediate state. `draft` is not a finished rendered visual. Follow [Create Visual](/rest-api-reference/create-video.md) when choosing `render` and template inputs.

Use `item.mediaUrl` or `item.imageUrls` only after generation succeeds. Those URLs are ready for publishing and do not need a separate upload.

## Uploads are a separate flow

A presigned upload response provides 2 URLs. Upload the file bytes to `presignedUrl`, wait for the upload to succeed, and use `publicUrl`. There is no upload-status MCP tool. See [Media uploads and conversion](/api-and-mcp-concepts/media-uploads-and-conversion.md).

For examples, see [Workflow recipes](/api-and-mcp-concepts/workflows.md). For failure recovery, see [Errors and retries](/api-and-mcp-concepts/error-handling.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.blotato.com/api-and-mcp-concepts/async-jobs-and-polling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.