API reference
List posts with filters for status, platform and dates, newest first, with offset pagination.
https://api.betterpost.dev/v1/posts| Name | Type | Default | Description |
|---|---|---|---|
status | string | draft, scheduled, pending, publishing, published, partial or failed. | |
platform | string | Repeatable: ?platform=twitter&platform=linkedin matches posts targeting any of them. | |
createdAfter | string | ISO 8601 date-time with Z or an offset (inclusive). | |
createdBefore | string | ISO 8601 date-time with Z or an offset (inclusive). | |
scheduledAfter | string | Scheduled time on or after this instant. | |
scheduledBefore | string | Scheduled time on or before this instant. | |
limit | integer | 20 | 1 to 100. |
offset | integer | 0 | Posts to skip. |
sort | string | desc | desc (newest first) or asc, by creation time. |
curl -s "https://api.betterpost.dev/v1/posts?status=partial&platform=linkedin&limit=20" \
-H "x-access-key: $BETTERPOST_API_KEY"200 OK
{
"success": true,
"total": 1,
"posts": [
{
"postId": "post_8f3k2m9q1x7v4n6b0c5d2a1z",
"content": "Ship it #fail:linkedin",
"status": "partial",
"scheduledFor": null,
"timezone": "UTC",
"mediaItems": [],
"platforms": [
{
"platform": "twitter",
"accountId": "acc_2x9c4v7b1n8m3k5j0h6g2f4d",
"status": "published",
"content": "Ship it #fail:linkedin",
"platformPostId": "sbx_1849203756184930275",
"platformPostUrl": "https://betterpost.dev/sandbox/p/twitter/sbx_1849203756184930275",
"publishedAt": "2026-10-21T14:10:02.551Z",
"errorMessage": null,
"warningMessage": null
},
{
"platform": "linkedin",
"accountId": "acc_5l1n7k3j9h2g8f4d6s0a1q3w",
"status": "failed",
"content": "Ship it #fail:linkedin",
"platformPostId": null,
"platformPostUrl": null,
"publishedAt": null,
"errorMessage": "Sandbox: simulated LinkedIn API error (triggered by #fail:linkedin)",
"warningMessage": null
}
],
"crosspostingEnabled": false,
"sandbox": true,
"createdAt": "2026-10-21T14:10:01.903Z",
"updatedAt": "2026-10-21T14:10:02.560Z"
}
]
}total counts every matching post. Each post has the fields described in Get a post.
| Status | Code | When |
|---|---|---|
200 | Success. | |
400 | validation_error | A filter value is invalid (for example limit=0 or a date without an offset). |
400 | invalid_platform | Unknown platform value. |
401 | unauthorized | Missing or unknown API key. |
403 | platform_not_available | A platform BetterPost does not support yet. |
429 | rate_limited | More than 120 requests per minute. |