Skip to main content
Posts

List Posts

Retrieve a paginated list of posts with filtering and sorting.

Endpoint

GET https://api.postpeer.dev/v1/posts

Query Parameters

ParameterTypeDefaultDescription
statusstring—Filter by status: "draft", "scheduled", "published", "failed", or "partial"
platformstring[]—Filter by platform (repeatable, OR logic). e.g. ?platform=twitter&platform=instagram
createdAfterstring—ISO 8601 lower bound on createdAt
createdBeforestring—ISO 8601 upper bound on createdAt
scheduledAfterstring—ISO 8601 lower bound on scheduledFor
scheduledBeforestring—ISO 8601 upper bound on scheduledFor
limitinteger20Page size (1–100)
offsetinteger0Number of posts to skip
sortstring"desc"Sort by createdAt: "asc" or "desc"

Example

curl "https://api.postpeer.dev/v1/posts?status=published&platform=twitter&limit=5" \
  -H "x-access-key: YOUR_API_KEY"

Response

{
  "success": true,
  "total": 42,
  "posts": [
    {
      "postId": "post_abc123",
      "content": "Hello world!",
      "status": "published",
      "scheduledFor": null,
      "timezone": "UTC",
      "mediaItems": [],
      "platforms": [
        {
          "platform": "twitter",
          "status": "published",
          "platformPostId": "1234567890",
          "platformPostUrl": "https://twitter.com/you/status/1234567890",
          "publishedAt": "2026-04-15T14:30:00.000Z",
          "errorMessage": null
        }
      ],
      "crosspostingEnabled": false,
      "createdAt": "2026-04-15T14:30:00.000Z",
      "updatedAt": "2026-04-15T14:30:01.000Z"
    }
  ]
}

Status Codes

CodeMeaning
200Success
400Invalid query parameters

Previous

Create Post

Next

Get Post

On this page