List posts

Returns a paginated list of posts.

Authorization

ApiKeyAuth

AuthorizationBearer <token>

PublishQ API key sent as Authorization: Bearer pq_live_....

In: header

Query Parameters

page?integer

Page number (starts from 1).

Default1

Range0 < value

limit?integer

Page size. Max 100.

Default20

Range0 < value <= 100

Response Body

`application/json`

curl -X GET "https://publishq.com/api/v1/posts"

{
  "posts": [
    {
      "id": "2b3c4d5e-6f7a-8901-bcde-f12345678901",
      "content": "Check out our latest product update!",
      "status": "SCHEDULED",
      "mediaIds": [
        "f6a7b8c9-d0e1-2345-6789-abcdef012345"
      ],
      "scheduledAt": "2026-04-05T14:00:00Z",
      "createdAt": "2026-04-01T08:30:00Z",
      "accounts": [
        {
          "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "platform": "TWITTER",
          "accountName": "@publishq",
          "status": "SCHEDULED",
          "postOverrides": {
            "content": "New product update just dropped 🔥 Thread below 👇"
          }
        },
        {
          "accountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "platform": "YOUTUBE",
          "accountName": "PublishQ Channel",
          "status": "SCHEDULED",
          "postOverrides": {
            "content": "Product Update April 2026"
          },
          "platformSpecificSettings": {
            "description": "Full walkthrough of our latest features. Timestamps below.\n\n0:00 Intro\n0:45 New API\n2:30 Dashboard updates",
            "privacyStatus": "public"
          }
        },
        {
          "accountId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "platform": "TIKTOK",
          "accountName": "publishq",
          "status": "SCHEDULED",
          "postOverrides": {
            "thumbnailTimestamp": 3500
          },
          "platformSpecificSettings": {
            "privacyLevel": "PUBLIC_TO_EVERYONE",
            "disableComment": false,
            "disableDuet": false,
            "disableStitch": false,
            "brandContentToggle": false,
            "brandOrganicToggle": false
          }
        },
        {
          "accountId": "d4e5f6a7-b8c9-0123-def0-1234567890ab",
          "platform": "INSTAGRAM",
          "accountName": "publishq_official",
          "status": "SCHEDULED",
          "platformSpecificSettings": {
            "postType": "REEL"
          }
        },
        {
          "accountId": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
          "platform": "BLUESKY",
          "accountName": "@publishq.bsky.social",
          "status": "SCHEDULED"
        }
      ]
    },
    {
      "id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321",
      "content": "Just shipped our new API — schedule posts to 8 platforms with one call 🚀",
      "status": "PUBLISHED",
      "mediaIds": [
        "d4c3b2a1-0987-6543-21fe-dcba09876543"
      ],
      "publishedAt": "2026-04-01T12:01:23Z",
      "createdAt": "2026-03-30T10:00:00Z",
      "accounts": [
        {
          "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "platform": "TWITTER",
          "accountName": "@publishq",
          "status": "PUBLISHED",
          "externalUrl": "https://x.com/publishq/status/1234567890",
          "publishedAt": "2026-04-01T12:01:05Z"
        },
        {
          "accountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "platform": "LINKEDIN",
          "accountName": "PublishQ Inc.",
          "status": "PUBLISHED",
          "externalUrl": "https://www.linkedin.com/feed/update/urn:li:share:7654321",
          "publishedAt": "2026-04-01T12:01:23Z"
        }
      ]
    },
    {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "content": "Happy holidays from the team! 🎄",
      "status": "FAILED",
      "error": "Publishing failed on 1 account: @oldhandle (Twitter). Check accounts[].errorMessage for details.",
      "mediaIds": [
        "e5f6a7b8-c9d0-1234-5678-9abcdef01234"
      ],
      "createdAt": "2026-03-30T09:00:00Z",
      "accounts": [
        {
          "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "platform": "TWITTER",
          "accountName": "@oldhandle",
          "status": "FAILED",
          "errorMessage": "Token expired. Please reconnect your Twitter account."
        },
        {
          "accountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "platform": "INSTAGRAM",
          "accountName": "publishq_official",
          "status": "PUBLISHED",
          "externalUrl": "https://www.instagram.com/p/ABC123/",
          "publishedAt": "2026-04-01T12:01:10Z",
          "platformSpecificSettings": {
            "postType": "REEL"
          }
        },
        {
          "accountId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "platform": "LINKEDIN",
          "accountName": "PublishQ Inc.",
          "status": "PUBLISHED",
          "externalUrl": "https://www.linkedin.com/feed/update/urn:li:share:9876543",
          "publishedAt": "2026-04-01T12:01:15Z"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

{
  "error": {
    "title": "Unauthorized",
    "status": 401,
    "code": "missing_auth",
    "message": "Missing Authorization header",
    "instance": "/api/v1/posts"
  }
}

{
  "error": {
    "title": "Too Many Requests",
    "status": 429,
    "code": "rate_limit_exceeded",
    "message": "Too Many Requests",
    "instance": "/api/v1/posts",
    "details": {
      "retryAfter": 60
    }
  }
}

Authorization

Query Parameters

Response Body

200application/json

401application/json

429application/json

Example missingAuth

Example invalidApiKey

`application/json`

`application/json`

`application/json`