> 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/post-lifecycle.md).

# 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](/api-and-mcp-concepts/async-jobs-and-polling.md).
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](/rest-api-reference/schedules.md) 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](/rest-api-reference/publish-post/list-posts.md) 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](/api-and-mcp-concepts/accounts-and-identifiers.md) 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](/start-with-an-ai-agent/publishing-status.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/post-lifecycle.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.