Skip to content

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.

Input contract
FieldLocationTypeRequiredDescription
postIdPathstringRequiredID of the failed post to retry.
scheduledForBodystring (date-time)OptionalOptional ISO 8601 time to schedule the retry. Omit to retry immediately.
timezoneBodystringOptionalIANA timezone for the scheduled retry (e.g. America/New_York). Defaults to UTC.
x-access-keyHeaderstringRequired by authorization contractaccessKey supplied in the x-access-key header.

Exact captured contract; origin replaced only by {{API_BASE_URL}}.

Response status matrix
StatusContent typeResponse shape
202application/jsonsuccess, status, scheduledFor, postId, platforms[] with platform, success, platformPostUrl, error, warningMessage
400application/jsonsuccess, message
402application/jsonsuccess, message
403application/jsonsuccess, message
404application/jsonsuccess, message
503application/jsonsuccess, 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.

Retry request example
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"
  }'
202 response example
{
  "success": true,
  "status": "draft",
  "scheduledFor": "2019-08-24T14:15:22Z",
  "postId": "string",
  "platforms": [
    {
      "platform": "twitter",
      "success": true,
      "platformPostUrl": "string",
      "error": "string",
      "warningMessage": "string"
    }
  ]
}
Error response example for 400, 402, 403, 404 and 503
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
postId#1postIdstring__0YesID of the failed post to retry.
body#2bodyobject__0Yes
body#2body.scheduledForstring__1NoOptional ISO 8601 time to schedule the retry. Omit to retry immediately.kind: schemaFormat; value: date-time
body#2body.timezonestring__2NoIANA timezone for the scheduled retry (e.g. America/New_York). Defaults to UTC.
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes