List Posts
GET /developers/v1/posts
Returns a paginated list of posts belonging to the authenticated user. You can filter by status and date range to narrow the results.
Request
Headers
| Header | Required | Description |
|---|---|---|
X-API-KEY | Yes* | Your personal API key. |
Authorization | Yes* | Bearer token: Bearer sp_tok_xxxxxxx. |
*Provide one of the two authentication headers.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status | string | No | all | Filter by post status. One of: scheduled, posted, failed, draft, pending_approval, all. |
start_date | string | No | — | Return posts scheduled on or after this date. Format: YYYY-MM-DD. |
end_date | string | No | — | Return posts scheduled on or before this date. Format: YYYY-MM-DD. |
page | integer | No | 1 | Page number for pagination. |
per_page | integer | No | 20 | Number of posts per page. Maximum: 100. |
Example request
curl "https://api.schedpilot.com/developers/v1/posts?status=scheduled&start_date=2026-06-01&end_date=2026-06-30&page=1&per_page=20" \
-H "X-API-KEY: smm_4a9f3c1e8b205d7a6e0f2c49b8d3a15f"
Response
Status: 200 OK
Top-level fields
| Field | Type | Description |
|---|---|---|
posts | array | Array of post objects matching the query. |
total | integer | Total number of posts matching the filter (across all pages). |
page | integer | Current page number. |
per_page | integer | Number of items per page as requested. |
Post object fields
| Field | Type | Description |
|---|---|---|
id | integer | Unique post ID. |
content | string | The post text. |
scheduled_date | string | Scheduled publish datetime in YYYY-MM-DD HH:MM:SS format. |
timezone | string | Timezone for scheduled_date. |
status | string | Current post status: scheduled, posted, failed, draft, or pending_approval. |
accounts | array | Per-platform delivery details (see below). |
images | array | Array of image URLs attached to the post. Empty array if none. |
videos | array | Array of video URLs attached to the post. Empty array if none. |
Account delivery object (within accounts)
| Field | Type | Description |
|---|---|---|
id | integer | The connected account ID. |
type | string | Platform type, e.g. "twitter", "linkedin". |
posted_status | string | Delivery status for this specific platform: scheduled, posted, failed. |
platform_post_id | string | null | The native post ID assigned by the platform after successful delivery. null if not yet published. |
Example response
{
"posts": [
{
"id": 8841,
"content": "Excited to announce our new product launch! Check it out at acme.com/launch",
"scheduled_date": "2026-06-15 14:30:00",
"timezone": "America/New_York",
"status": "scheduled",
"accounts": [
{
"id": 12,
"type": "twitter",
"posted_status": "scheduled",
"platform_post_id": null
},
{
"id": 17,
"type": "linkedin",
"posted_status": "scheduled",
"platform_post_id": null
}
],
"images": [
"https://api.schedpilot.com/wp-content/uploads/smm/image-42.jpg"
],
"videos": []
},
{
"id": 8790,
"content": "Our weekly roundup is live. Read it on the blog.",
"scheduled_date": "2026-06-08 09:00:00",
"timezone": "UTC",
"status": "posted",
"accounts": [
{
"id": 12,
"type": "twitter",
"posted_status": "posted",
"platform_post_id": "1801234567890123456"
},
{
"id": 23,
"type": "instagram",
"posted_status": "posted",
"platform_post_id": "17895695668004550"
}
],
"images": [],
"videos": []
}
],
"total": 47,
"page": 1,
"per_page": 20
}
Error responses
| Status | Description |
|---|---|
400 Bad Request | Invalid parameter value (e.g. unrecognised status string, malformed date). |
401 Unauthorized | Missing or invalid authentication credentials. |
429 Too Many Requests | Read rate limit exceeded (60 requests/hour). |