List Social Posts

List the social posts in your workspace, newest first

Published Aug 11, 2026·Updated Oct 27, 2026

GET

/v1/social/posts

curl -X GET "https://api.orshot.com/v1/social/posts?status=<STATUS>&platform=<PLATFORM>&account_id=10" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

const res = await fetch("https://api.orshot.com/v1/social/posts?status=<STATUS>&platform=<PLATFORM>&account_id=10", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

const data = await res.json();

import requests

response = requests.get(
    "https://api.orshot.com/v1/social/posts?status=<STATUS>&platform=<PLATFORM>&account_id=10",
    headers={"Authorization": "Bearer <ORSHOT_API_KEY>"},
)

data = response.json()

$ch = curl_init("https://api.orshot.com/v1/social/posts?status=<STATUS>&platform=<PLATFORM>&account_id=10");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <ORSHOT_API_KEY>",
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

require "net/http"
require "json"

uri = URI("https://api.orshot.com/v1/social/posts?status=<STATUS>&platform=<PLATFORM>&account_id=10")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Overview#

Returns the social posts in your workspace — drafts waiting for review, scheduled posts, and everything already published or failed. This is the same history the Posts Log shows in your dashboard.

Use it to find a post's id before reading, editing, publishing or discarding it.

Endpoint

https://api.orshot.com/v1/social/posts

Request#

JavaScript

await fetch("https://api.orshot.com/v1/social/posts?status=draft&limit=10", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

JSON

{
  "data": [
    {
      "id": 512,
      "status": "draft",
      "content": "Our new pricing is live.",
      "media_urls": ["https://storage.orshot.com/.../launch.png"],
      "platforms": ["linkedin", "twitter"],
      "accounts": [
        {
          "account_id": 15,
          "platform": "linkedin",
          "username": "acme-inc",
          "name": "Acme Inc",
          "status": "draft"
        },
        {
          "account_id": 22,
          "platform": "twitter",
          "username": "acmehq",
          "name": "Acme",
          "status": "draft"
        }
      ],
      "is_editable": true,
      "scheduled_for": null,
      "published_at": null,
      "created_at": "2026-08-11T17:24:09.752914+00:00",
      "render_id": 889021
    }
  ],
  "pagination": {
    "limit": 10,
    "has_more": false,
    "next_cursor": null
  }
}

Query Parameters#

Parameter	Type	Required	Description
`status`	String	No	Only posts in this state: `draft`, `scheduled`, `published`, `processing`, `partial`, `failed`
`platform`	String	No	Only posts targeting this platform, e.g. `linkedin`
`account_id`	Integer	No	Only posts targeting this connected account
`limit`	Integer	No	Posts per page, 1–50 (default 25)
`cursor`	Integer	No	`next_cursor` from a previous response, to fetch the next older page

Pass status=draft to list exactly the posts that are being held and have not reached any platform.

Post Object#

Every endpoint that returns a post returns this shape.

Field	Type	Description
`id`	Integer	Post ID. Use it with the other post endpoints
`status`	String	`draft`, `scheduled`, `published`, `processing`, `partial` or `failed`
`content`	String	The caption
`media_urls`	Array	Media attached to the post
`tags`	Array	Labels you set when publishing
`platforms`	Array	Platform names this post targets
`accounts`	Array	Per-account results — the detailed view of `platforms`
`accounts[].account_id`	Integer	The exact connected account. `null` on posts created before per-account results existed
`accounts[].platform`	String	Platform of this account
`accounts[].username`	String	Account handle
`accounts[].name`	String	Account display name
`accounts[].status`	String	This account's own outcome
`accounts[].url`	String	Link to the live post, once published
`accounts[].error`	String	Why this account failed, when it did
`accounts[].action`	String	Suggested fix when this account failed, e.g. `reconnect`
`is_editable`	Boolean	Whether Orshot is still holding this post, i.e. whether it can be edited or published
`is_discardable`	Boolean	Whether it can be deleted — true unless at least one account already went live
`scheduled_for`	String	When it will publish, if scheduled
`published_at`	String	When it published
`created_at`	String	When it was created
`render_id`	Integer	The render this post came from, when it was created by rendering a template
`error_message`	String	Only present when something failed after the request returned, e.g. a discard the platform did not confirm

Branch on the two capability flags rather than on status — they are not the same test:

is_editable is true only while the post is held (draft or scheduled). Editing and publishing require it.
is_discardable is true unless at least one account already published. A failed post is discardable but not editable; a partial post is neither.

Error Responses#

Invalid cursor (400)#

JSON

{
  "error": "Invalid cursor",
  "message": "cursor must be a post id"
}

Unauthorized (403)#

JSON

{
  "error": "Access Forbidden"
}

Rate Limits#

20 requests per minute per workspace, shared by the publishing and post endpoints. Analytics has its own limit

Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key

Image, PDF and video generation via API
Visual editor with AI and smart layouts
Zapier, Make, MCP and 40+ integrations
White-label embed for your own app
100 free credits a month, no credit card required