List Social Posts

List the social posts in your workspace, newest first

Published Aug 11, 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
`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[].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
`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

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 across all social endpoints

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 50+ integrations
White-label embed for your own app
30 free credits — no credit card required