Post Items
List published post items and retry failed ones.
Post items are the per-platform rows under a post — what actually went live (or failed) on Instagram, TikTok, and the rest.
List Published Posts
GET /api/v1/post-items
List published post items (what went live on each platform). One row per platform target. Newest first.
Only items with status posted are returned. Drafts, scheduled posts, and failed items are not included.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
platform | string | No | Filter by platform. One name or a comma-separated list. See Post types. Omit for all. |
from | string | No | Start date, inclusive. Date only: YYYY-MM-DD (no time). UTC calendar day. |
to | string | No | End date, inclusive. Date only: YYYY-MM-DD (no time). UTC calendar day. |
limit | number | No | Max results (1–100, default 20) |
When both from and to are set, to must be on or after from, and the range must not exceed 90 days.
Dates use UTC day boundaries. A post with posted_at of 2026-07-10T23:00:00Z is included when from=2026-07-10 and to=2026-07-10. Timestamps with a time component (e.g. 2026-07-10T12:00:00Z) are rejected.
There is no cursor pagination. Raise limit or narrow the date range if you need more results.
Example
curl "https://powerpost.ai/api/v1/post-items?platform=instagram,tiktok&from=2026-07-01&to=2026-07-07&limit=20" \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID"Response
{
"data": [
{
"item_id": "item-001",
"post_id": "post-550e8400-e29b-41d4-a716-446655440000",
"post_type": "instagram-reel",
"platform": "instagram",
"content": "Dark mode is here!...",
"media_ids": ["img-001-abcd-efgh"],
"status": "posted",
"platform_post_id": "17898455678012345",
"platform_url": "https://instagram.com/p/CxYz123abc/",
"posted_at": "2026-07-05T14:22:00Z"
},
{
"item_id": "item-002",
"post_id": "post-550e8400-e29b-41d4-a716-446655440000",
"post_type": "tiktok-video",
"platform": "tiktok",
"content": "POV: dark mode finally shipped...",
"media_ids": ["img-001-abcd-efgh"],
"status": "posted",
"platform_post_id": "7123456789012345678",
"platform_url": "https://www.tiktok.com/@you/video/7123456789012345678",
"posted_at": "2026-07-05T14:22:05Z"
}
]
}posted_at in the response is the real publish timestamp (ISO datetime). Only the from / to filters are date-only.
Use item_id with Get Post Item Analytics or post_id with Get Post for the full parent.
Retry Post Item
POST /api/v1/post-items/{id}/retry
Retries one failed item from a sent post. The item moves back through posting and resolves to posted or failed.
Response
{
"post_item_id": "item-003",
"status": "posting",
"task_id": "run_123"
}Related
- Analytics — Performance metrics for an item
- Posts — Parent post create/get
- Publish & schedule — Publish flow