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	GET /v2/videos/creations/:id (REST only)	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. For queued comments and messages, space status checks to stay within the endpoint rate limits.

3. 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.

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. Wait at least 15 seconds between visual status calls (GET /v2/videos/creations/:id). 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 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.

For examples, see Workflow recipes. For failure recovery, see Errors and retries.