Get Post Status

Look up a submission ID to distinguish processing, scheduled, published, and failed results without repeating a write.

Check Post Status

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /posts/:postSubmissionId

Method: GET

Rate Limit: 60 requests / minute

Description

Poll this endpoint to check the publishing status of a post. After submitting a post with Create Post, use the returned postSubmissionId to track its progress.

The lookup checks failed, published, and scheduled records belonging to the authenticated Blotato user. If none matches, it returns in-progress. This fallback does not confirm a live queue job or validate a guessed submission ID. Use the original create response and account credentials.

Request

Path Parameters

Field	Type	Required	Description
postSubmissionId	string	Yes	The post submission ID returned by the Create Post endpoint.

Responses

Success Response

Status Code: 200 OK

The response shape depends on the current status:

Published (terminal - success):

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "published",
  "publicUrl": "https://x.com/user/status/123456"
}

Failed (terminal - error):

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "errorMessage": "Unsupported media type"
}

In Progress (keep polling):

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "in-progress"
}

Scheduled (queued for a future time):

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "scheduled",
  "scheduledTime": "2025-03-10T15:30:00Z"
}

Response Keys

Field	Type	Description
postSubmissionId	string	The post submission ID.
status	string	One of: in-progress, scheduled, published, failed.
scheduledTime	string	The scheduled publish time. Present when status is scheduled.
publicUrl	string	URL returned for a published result, when available. The field is optional.
errorMessage	string	Description of the failure. Present when status is failed.

Polling Strategy

1. Wait at least 10 seconds between status requests.

2. Continue while status is in-progress, within a defined attempt or elapsed-time limit. Verify the ID came from the original create response.

3. If status is scheduled, report the returned scheduledTime and stop this polling loop. Scheduling is confirmed, not publication.

4. Stop when status is published (success) or failed (error).

5. On failed, inspect errorMessage and the destination before deciding whether a corrected or delayed retry is appropriate. Do not repeat a create request blindly.

If the result remains unresolved, retain the ID and follow publishing-status diagnosis. A polling deadline is not proof of failure.

Failed posts are also visible at https://my.blotato.com/posts?status=failed.

Example

GET https://backend.blotato.com/v2/posts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1
blotato-api-key: YOUR_API_KEY