Post lifecycle

Distinguish submission, scheduling, publication, and failure states and retain the matching identifiers.

A post moves through submission, processing, and a published or failed outcome. Scheduling adds a wait until the chosen time.

Result	Meaning	Agent response
Create response with postSubmissionId	Blotato accepted the request	Save the ID
in-progress	No failed, published, or scheduled result was found	Verify the saved submission ID and poll within a waiting limit
scheduled	The post is scheduled	Report scheduledTime and stop immediate polling
published	Publishing completed	Return publicUrl when supplied
failed	Publishing stopped	Explain errorMessage and resolve the cause

Publish now

1. Fetch the destination account and required IDs.

2. Submit the post once.

3. Follow status polling.

4. Report the returned outcome.

Publish later

1. Resolve the user's requested date, time, and timezone.

2. Submit with a future scheduledTime or useNextFreeSlot: true.

3. Report the resolved UTC time in the user's timezone.

4. Use scheduled-post management for later edits or cancellation.

Do not keep polling a future scheduled post as if publication should finish now. Check publication after its scheduled time when the task requires it.

Look up existing work

Use List Posts to inspect published, scheduled, and failed records. Its state.type values describe list items, while the submission-status endpoint uses the status values above.

Keep submission, scheduled, and published post IDs separate. A retry after an uncertain network result starts with looking up existing work. Repeating create-post risks a duplicate.

The submission-status endpoint does not verify a live queue job before returning in-progress. This fallback also applies when it finds no record for the supplied ID. Use the ID from the original create response and the original Blotato account credentials. Do not treat an arbitrary ID returning in-progress as evidence of accepted work. For missing or conflicting records, follow Find a post's outcome before retrying.