# Posts

The Posts API lets you list, filter, and inspect social media posts across your connected accounts. Build dashboards, content calendars, or analytics by combining powerful query parameters.

### Requirements

* **Authentication**: Bearer API token
* **Scope**: `posts`
* **Headers**:
  * `Authorization: Bearer-API YOUR_API_KEY`
  * `Publer-Workspace-Id: YOUR_WORKSPACE_ID`

### Endpoint

#### List Posts

Retrieve posts with optional filters and pagination.

```http
GET /api/v1/posts
```

#### Query Parameters

<table><thead><tr><th width="147.7412109375">Parameter</th><th width="77.00274658203125">Type</th><th width="155.2493896484375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>state</code></td><td>string</td><td>No</td><td>Filter by a single post state (see <strong>State Values</strong> below)</td></tr><tr><td><code>state[]</code></td><td>array</td><td>No</td><td>Filter by multiple post states</td></tr><tr><td><code>from</code></td><td>string</td><td>Yes if <code>to</code> used</td><td>ISO date or datetime; include posts on/after this timestamp</td></tr><tr><td><code>to</code></td><td>string</td><td>Yes if <code>from</code> used</td><td>ISO date or datetime; include posts on/before this timestamp</td></tr><tr><td><code>page</code></td><td>integer</td><td>No</td><td>Page number (default: 0)</td></tr><tr><td><code>account_ids[]</code></td><td>array</td><td>No</td><td>List of account IDs to filter by</td></tr><tr><td><code>query</code></td><td>string</td><td>No</td><td>Full-text search keyword in post content</td></tr><tr><td><code>postType</code></td><td>string</td><td>No</td><td>Filter by post type (see <strong>Type Values</strong> below)</td></tr><tr><td><code>member_id</code></td><td>string</td><td>No</td><td>Filter posts created by a specific workspace member</td></tr></tbody></table>

**State Values**

<table data-header-hidden><thead><tr><th width="237.26531982421875"></th><th></th></tr></thead><tbody><tr><td>Value</td><td>Description</td></tr><tr><td><code>all</code></td><td>All posts regardless of state</td></tr><tr><td><code>scheduled</code></td><td>All scheduled posts</td></tr><tr><td><code>scheduled_approved</code></td><td>Scheduled posts that have been approved</td></tr><tr><td><code>scheduled_pending</code></td><td>Scheduled posts pending approval</td></tr><tr><td><code>scheduled_declined</code></td><td>Scheduled posts that were declined</td></tr><tr><td><code>scheduled_reauth</code></td><td>Scheduled posts requiring account reauthorization</td></tr><tr><td><code>scheduled_locked</code></td><td>Scheduled posts that are locked</td></tr><tr><td><code>published</code></td><td>All published posts</td></tr><tr><td><code>published_posted</code></td><td>Posts that were successfully published</td></tr><tr><td><code>published_deleted</code></td><td>Published posts that were deleted</td></tr><tr><td><code>published_hidden</code></td><td>Published posts that were hidden</td></tr><tr><td><code>draft</code></td><td>All draft posts</td></tr><tr><td><code>draft_dated</code></td><td>Draft posts with a scheduled date</td></tr><tr><td><code>draft_undated</code></td><td>Draft posts without a scheduled date</td></tr><tr><td><code>draft_private</code></td><td>Private draft posts</td></tr><tr><td><code>draft_public</code></td><td>Public draft posts</td></tr><tr><td><code>failed</code></td><td>Posts that failed to publish</td></tr><tr><td><code>recycling</code></td><td>All recycling posts</td></tr><tr><td><code>recycling_active</code></td><td>Active recycling posts</td></tr><tr><td><code>recycling_paused</code></td><td>Paused recycling posts</td></tr><tr><td><code>recycling_expired</code></td><td>Expired recycling posts</td></tr><tr><td><code>recycling_failed</code></td><td>Failed recycling posts</td></tr><tr><td><code>recycling_pending</code></td><td>Recycling posts pending approval</td></tr><tr><td><code>recycling_declined</code></td><td>Recycling posts that were declined</td></tr><tr><td><code>recycling_reauth</code></td><td>Recycling posts requiring account reauthorization</td></tr><tr><td><code>recycling_locked</code></td><td>Recycling posts that are locked</td></tr><tr><td><code>recurring</code></td><td>Recurring posts</td></tr></tbody></table>

**Type Values**

<table data-header-hidden><thead><tr><th width="127.1854248046875"></th><th></th></tr></thead><tbody><tr><td>Value</td><td>Description</td></tr><tr><td><code>status</code></td><td>Text-only posts</td></tr><tr><td><code>link</code></td><td>Posts with links</td></tr><tr><td><code>photo</code></td><td>Photo posts</td></tr><tr><td><code>gif</code></td><td>GIF posts</td></tr><tr><td><code>video</code></td><td>Video posts</td></tr><tr><td><code>reel</code></td><td>Instagram or Facebook reels</td></tr><tr><td><code>story</code></td><td>Instagram or Facebook stories</td></tr><tr><td><code>short</code></td><td>YouTube shorts</td></tr><tr><td><code>poll</code></td><td>Poll posts</td></tr><tr><td><code>document</code></td><td>Document posts</td></tr><tr><td><code>carousel</code></td><td>Multi-image carousel posts</td></tr><tr><td><code>article</code></td><td>Article/blog posts</td></tr></tbody></table>

## List Posts

> Retrieves a list of posts based on the specified filters.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Posts","description":"Endpoints for managing social media posts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"PostsListResponse":{"type":"object","properties":{"posts":{"type":"array","description":"List of posts matching the query parameters","items":{"$ref":"#/components/schemas/PostSummary"}},"total":{"type":"integer","description":"Total number of posts matching the query"},"page":{"type":"integer","description":"Current page number"},"per_page":{"type":"integer","description":"Number of posts per page"},"total_pages":{"type":"integer","description":"Total number of pages"}}},"PostSummary":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the post"},"text":{"type":"string","description":"Post text content"},"url":{"type":"string","description":"URL for link posts"},"state":{"type":"string","description":"Current state of the post"},"type":{"type":"string","description":"Type of post"},"account_id":{"type":"string","description":"ID of the social account"},"user":{"type":"object","description":"User who created the post","properties":{"id":{"type":"string"},"name":{"type":"string"},"picture":{"type":"string"}}},"scheduled_at":{"type":"string","description":"Scheduled publication time"},"post_link":{"type":"string","description":"Link to the published post on the social network"},"has_media":{"type":"boolean","description":"Indicates if the post contains media"},"network":{"type":"string","description":"Social network for this post"}}},"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/posts":{"get":{"summary":"List Posts","description":"Retrieves a list of posts based on the specified filters.","tags":["Posts"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve posts from","required":true},{"schema":{"type":"string","enum":["all","scheduled","scheduled_approved","scheduled_pending","scheduled_declined","scheduled_reauth","scheduled_locked","published","published_posted","published_deleted","published_hidden","draft","draft_dated","draft_undated","draft_private","draft_public","failed","recycling","recycling_active","recycling_paused","recycling_expired","recycling_failed","recycling_pending","recycling_declined","recycling_reauth","recycling_locked","recurring"]},"name":"state","in":"query","description":"Filter by post state\n\n Available options: \n\n `all`, `scheduled`, `scheduled_approved`, `scheduled_pending`, `scheduled_declined`, `scheduled_reauth`, `scheduled_locked`, `published`, `published_posted`, `published_deleted`, `published_hidden`, `draft`, `draft_dated`, `draft_undated`, `draft_private`, `draft_public`, `failed`, `recycling`, `recycling_active`, `recycling_paused`, `recycling_expired`, `recycling_failed`, `recycling_pending`, `recycling_declined`, `recycling_reauth`, `recycling_locked`, `recurring`","required":false},{"schema":{"type":"array","items":{"type":"string","enum":["all","scheduled","scheduled_approved","scheduled_pending","scheduled_declined","scheduled_reauth","scheduled_locked","published","published_posted","published_deleted","published_hidden","draft","draft_dated","draft_undated","draft_private","draft_public","failed","recycling","recycling_active","recycling_paused","recycling_expired","recycling_failed","recycling_pending","recycling_declined","recycling_reauth","recycling_locked","recurring"]}},"style":"form","explode":true,"name":"state","in":"query","description":"Filter by multiple post states\n\n Available options: \n\n `all`, `scheduled`, `scheduled_approved`, `scheduled_pending`, `scheduled_declined`, `scheduled_reauth`, `scheduled_locked`, `published`, `published_posted`, `published_deleted`, `published_hidden`, `draft`, `draft_dated`, `draft_undated`, `draft_private`, `draft_public`, `failed`, `recycling`, `recycling_active`, `recycling_paused`, `recycling_expired`, `recycling_failed`, `recycling_pending`, `recycling_declined`, `recycling_reauth`, `recycling_locked`, `recurring`","required":false},{"schema":{"type":"string","format":"date"},"name":"from","in":"query","description":"Filter posts scheduled/published after this date \n\n- Example: 2025-05-15 \n\n Required if `to` is provided","required":false},{"schema":{"type":"string","format":"date"},"name":"to","in":"query","description":"Filter posts scheduled/published before this date \n\n- Example: 2025-05-15 \n\n Required if `from` is provided","required":false},{"schema":{"type":"integer"},"name":"page","in":"query","description":"Page number for pagination","required":false},{"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"name":"account_ids","in":"query","description":"Filter posts by multiple account IDs","required":false},{"schema":{"type":"string"},"name":"query","in":"query","description":"Search query to filter posts by content","required":false},{"schema":{"type":"string","enum":["status","link","photo","gif","video","reel","story","short","poll","document","carousel","article"]},"name":"postType","in":"query","description":"Filter by post type \n\n Available options: \n\n `status`, `link`, `photo`, `gif`, `video`, `reel`, `story`, `short`, `poll`, `document`, `carousel`, `article`","required":false},{"schema":{"type":"string"},"name":"member_id","in":"query","description":"Filter posts by team member ID","required":false}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostsListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

### Filtering Examples

* **Photo posts scheduled next month containing “launch”**\
  `GET /posts?state=scheduled&postType=photo&from=2025-06-01&to=2025-06-30&query=launch`
* **All failed posts across accounts**\
  `GET /posts?state=failed&account_ids[]=63c675b54e299e9cf2b667ea&account_ids[]=64d786c54e299e9cf2b667fb`
* **Drafts by a workspace member**\
  `GET /posts?state=draft&member_id=5b1ec026db27977424e8599e`

### Related Resources

* [Accounts API](https://publer.com/docs/api-reference/accounts) - List social media accounts
* [Media API](https://publer.com/docs/posting/create-posts/media-handling) - Upload and manage media for posts
* [Create Posts](https://publer.com/docs/posting/create-posts) - Post creation endpoints


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://publer.com/docs/api-reference/posts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.