Retry Post API
The Retry Post API re-publishes only the failed platforms of an existing post. Call POST /v1/posts/{postId}/retry with the postId of the failed post, omit scheduledFor to retry immediately, or pass scheduledFor in ISO 8601 format to schedule the retry. Already-published platforms are never re-posted.
Retry Post API overview
The Retry Post API re-publishes only the failed platforms of a post. Use the exact endpoint POST /v1/posts/{postId}/retry, replacing only the origin with {{API_BASE_URL}} in examples. Omit scheduledFor to retry immediately, or pass scheduledFor as an ISO 8601 date-time to schedule the retry. Already-published platforms are never re-posted, so the operation is scoped to failed platform targets rather than the whole post.
Authorization
Send the access key in the x-access-key header. The authorization contract is accessKey in the x-access-key header, with the token supplied as the header value. Requests without the expected header do not match this contract.
Path Parameters
The path parameter postId is a required string and is the ID of the failed post to retry. Place it in the {postId} segment of /v1/posts/{postId}/retry. Verify the identifier against the existing post before calling, because the retry is addressed to that specific post.
Request Body
Send an application/json request body. The scheduledFor field is an optional string in date-time format; omit it to retry immediately. The timezone field is an optional string containing an IANA timezone such as America/New_York for the scheduled retry, and it defaults to UTC. Both fields are optional, so an empty JSON object matches the immediate-retry form shown in the request example.
Worked example
The worked example uses {{API_BASE_URL}} before the unchanged path /v1/posts/{postId}/retry. It sends Content-Type application/json and the x-access-key header, then supplies scheduledFor and timezone in the body. For an immediate retry, remove scheduledFor and timezone from the body while keeping the same method, path, and headers.
Response Body
A 202 application/json response contains success, status, scheduledFor, postId, and a platforms array. Each platform entry in the captured example contains platform, success, platformPostUrl, error, and warningMessage. The other listed statuses, 400, 402, 403, 404, and 503, each return application/json with a success and message object. Check the status code first, then inspect the platform entries for platformPostUrl, error, and warningMessage on a 202 response.
Retry behavior and credit notes
Retried platforms are charged credits because they were refunded when they failed, and they are refunded again if they fail again. Plan retry logic around that credit behavior: a retry is not free, and a repeated failure restores the refund for the retried platform. Do not assume already-published platforms will be charged or posted again, because they are excluded from the retry.
| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| postId | Path | string | Required | ID of the failed post to retry. |
| scheduledFor | Body | string (date-time) | Optional | Optional ISO 8601 time to schedule the retry. Omit to retry immediately. |
| timezone | Body | string | Optional | IANA timezone for the scheduled retry (e.g. America/New_York). Defaults to UTC. |
| x-access-key | Header | string | Required by authorization contract | accessKey supplied in the x-access-key header. |
Exact captured contract; origin replaced only by {{API_BASE_URL}}.
| Status | Content type | Response shape |
|---|---|---|
| 202 | application/json | success, status, scheduledFor, postId, platforms[] with platform, success, platformPostUrl, error, warningMessage |
| 400 | application/json | success, message |
| 402 | application/json | success, message |
| 403 | application/json | success, message |
| 404 | application/json | success, message |
| 503 | application/json | success, message |
Limited to listed statuses; no meanings invented for undocumented codes.
Frequently asked questions
How do I retry failed platforms immediately?
Omit scheduledFor from the JSON body. The endpoint then retries the failed platforms immediately, subject to the response contract described on this page.
How do I schedule a retry instead of running it immediately?
Pass scheduledFor as an ISO 8601 date-time string and, when needed, timezone as an IANA timezone string. The timezone defaults to UTC when omitted.
Will a retry re-post platforms that already succeeded?
No. Already-published platforms are never re-posted. Only the platform targets that failed are re-published.
How are credits handled on a retry?
Retried platforms are charged credits because they were refunded when they failed, and they are refunded again if they fail again.
curl -X POST "{{API_BASE_URL}}/v1/posts/{postId}/retry" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"scheduledFor": "2019-08-24T14:15:22Z",
"timezone": "America/New_York"
}'{
"success": true,
"status": "draft",
"scheduledFor": "2019-08-24T14:15:22Z",
"postId": "string",
"platforms": [
{
"platform": "twitter",
"success": true,
"platformPostUrl": "string",
"error": "string",
"warningMessage": "string"
}
]
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| postId#1 | postId | string | __0 | Yes | ID of the failed post to retry. | |
| body#2 | body | object | __0 | Yes | ||
| body#2 | body.scheduledFor | string | __1 | No | Optional ISO 8601 time to schedule the retry. Omit to retry immediately. | kind: schemaFormat; value: date-time |
| body#2 | body.timezone | string | __2 | No | IANA timezone for the scheduled retry (e.g. America/New_York). Defaults to UTC. | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |