Skip to content
Relay Port

Reliability

What happens between your API call and the platform.

We never send the same post twice on our own, and we tell you when a platform's response is ambiguous. This page shows the rules behind that sentence.

01States

A target is always in one state.

Each target of a post has its own status. These are the moves it can make, read from the same table the scheduler uses.

Target status transitionsA diagram of the target statuses with a numbered arrow for each allowed move. The same moves are listed below the diagram.draftscheduledpublishingpublishedcancelledfailedunconfirmed12345678910
  1. 01draft to scheduledA post with mode schedule or queue, or publishing a draft
  2. 02scheduled to publishingThe workflow claim step wins the compare-and-set
  3. 03scheduled to cancelledDELETE /posts/{id}
  4. 04publishing to publishedThe platform confirmed it with a media ID, a published status or a completed status
  5. 05publishing to failedA pre-flight failure after the claim, a definite rejection, or a container error or expiry, nothing went live
  6. 06publishing to unconfirmedAn ambiguous publish response that reconciliation could not settle
  7. 07unconfirmed to publishedA late reconciliation read, or you resolve it
  8. 08unconfirmed to failedA late reconciliation read, or you resolve it
  9. 09failed to scheduledYou edit the post or retry it, which starts a new revision
  10. 10unconfirmed to scheduledYou edit the post or retry it with includeUnconfirmed, which starts a new revision
draft
Saved, not scheduled.
scheduled
Waiting for its due time.
publishing
The publish call has been claimed.
published
The platform confirmed it.
cancelled
Cancelled before it started.
failed
Nothing went live.
unconfirmed
Sent, and the platform's answer was unclear.

The post's status comes from its targets. All published is published, all failed is failed, and all unconfirmed is unconfirmed, never shown as failed. Any other mix is partial.

02Guarantees

Four guarantees, and nothing more.

These are the promises. We do not promise more, because a platform can publish a post and fail to tell us. That is what the fourth one is for.

Four guarantees, and nothing more.
GuaranteeWhat you can rely onWhere you see it
01 At most one publish callRelay Port makes the platform's publish call at most once per target revision on its own. A new revision exists only when you edit or retry the post.The target's timeline, GET /posts/{id}/events
02 Same key, same postA repeated API call with the same Idempotency-Key returns the same post, so your code can retry a request that timed out.The response header Idempotent-Replayed: true
03 A 24-hour duplicate guardIdentical content to the same account within 24 hours is refused, unless you set allowDuplicate to true.409 DuplicateContent
04 Ambiguous means unconfirmedWhen a platform's answer is ambiguous, the target becomes unconfirmed and the evidence is attached to it.status unconfirmed, with error.evidence

Read the details in Idempotency and duplicates.

03Instagram

When Instagram's answer is unclear, we read. We do not resend.

Reconciliation is made only of reads. None of them can create a post, so none of them can duplicate one.

  1. 01The publish call fails or times out after it may have reached Instagram.
  2. 02We read the status code of the media container.
  3. 03We read the account's recent media, from a little before the call was sent, and look for a match.
  4. 04We check again with waits in between, for a limited time.
  5. 05The result is published, not published, or undetermined, each with the evidence behind it.
Published
The target becomes published.
Not published
The target becomes failed. A retry is safe.
Undetermined
The target becomes unconfirmed.

04Unconfirmed

What unconfirmed means.

Instagram may have published the post. We could not prove it either way, so we did not send it again, and we did not call it failed.

Look at the account. Then call POST /posts/{id}/targets/{targetId}/resolve with outcome published or failed.

Retrying with includeUnconfirmed is the only way to send it again, and that is your decision.

Read Unconfirmed targets.

05Retries

Retries happen only before the publish call.

Steps that cannot create a public post are retried. The step that can is not.

Retried

  • Claiming the target for publishing
  • Checking the post, the account and the media again
  • Waiting for the platform's rate limits
  • Refreshing the access token
  • Creating the media containers
  • Polling until the media is ready
  • The reads that reconcile an unclear answer
  • Fetching the permalink and recording the result

Never retried

  • The publish call itself

06Webhooks

How webhooks are delivered.

Deliveries follow the Standard Webhooks specification. They arrive at least once and in no fixed order, so deduplicate on webhook-id.

  • Every delivery carries the headers webhook-id, webhook-timestamp, webhook-signature.
  • Reject a signature whose timestamp is more than 5 minutes away from your clock.
  • Answer with a success status code within 10 seconds.
  • A failed delivery is retried 10 times, after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours, 1 day, 1 day.
  • An endpoint that keeps failing for 3 days is marked failing.
  • After 7 days it is disabled, and the workspace's owners and admins are emailed.

Events

Publishing

post.scheduled
A post was scheduled for later.
post.updated
A scheduled post was edited.
post.cancelled
A scheduled post was cancelled before any target started publishing.
post.target.publishing
Publishing started for one target of a post.
post.target.published
One target of a post was published.
post.target.failed
One target of a post failed and nothing was published to it.
post.target.unconfirmed
The platform did not confirm one target. It was not sent again; check the account before retrying.
post.target.resolved
An unconfirmed target was marked published or not published.
post.published
Every target of a post was published.
post.partial
A post settled with some targets published and others not.
post.failed
Every target of a post failed.

Connections

account.connected
A social account was connected or reconnected.
account.disconnected
A social account was disconnected.
account.action_required
A social account needs an action on the platform before it can publish.
account.reconnect_required
A social account must be reconnected before it can publish.

Media

media.ready
An uploaded media file passed its checks and can be attached to posts.
media.failed
An uploaded media file failed its checks.

Webhooks

webhook.test
A test event sent to one webhook endpoint.

Billing and usage

billing.past_due
A payment failed and the 7-day grace started.
billing.blocked
The grace ended and new posts and connections are paused.
billing.recovered
The open invoice was paid and service resumed.
usage.threshold
A usage meter reached 80% or 100% of its plan limit

Read Webhooks.

07Retention

How long delivery logs are kept.

Webhook delivery logs and request logs are kept for the log retention of your plan.

How long delivery logs are kept.
PlanRetention
Free7 days
Pro30 days
Business90 days
Enterprise90 days

08Half-fail

A post where one account fails.

A post to two Instagram accounts, A and B.

  1. 01You send POST /posts with an Idempotency-Key. The call returns 201 and both targets are scheduled.
  2. 02Account A's target reaches published, and post.target.published is sent to your webhook endpoint.
  3. 03Account B's target is rejected before anything reaches Instagram, for example because a carousel has too few items. It becomes failed with the platform's reason, and post.target.failed is sent.
  4. 04The post's status is partial: one target published, one failed. post.partial is sent.
  5. 05You fix the media and call POST /posts/{id}/retry. Only the failed target starts a new revision. Account A's target is not touched.

If account B's target had been unconfirmed instead, the post would still be partial. Its target would carry the evidence, and you would check the account before retrying.

09Measured

What we have measured.

A figure appears here only when it has been measured, with its date and its method.

No measured figures yet.