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.

GET /api/v1/posts

Query Parameters

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

State Values

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

Type Values

Value	Description
status	Text-only posts
link	Posts with links
photo	Photo posts
gif	GIF posts
video	Video posts
reel	Instagram or Facebook reels
story	Instagram or Facebook stories
short	YouTube shorts
poll	Poll posts
document	Document posts
carousel	Multi-image carousel posts
article	Article/blog posts

List Posts

get

Retrieves a list of posts based on the specified filters.

Authorizations

BearerApiAuth

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Query parameters

statestring · enumOptional

Filter by post state

Available options:

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

Possible values:

fromstring · dateOptional

Filter posts scheduled/published after this date

• Example: 2025-05-15

Required if to is provided

tostring · dateOptional

Filter posts scheduled/published before this date

• Example: 2025-05-15

Required if from is provided

pageintegerOptional

Page number for pagination

account_idsstring[]Optional

Filter posts by multiple account IDs

querystringOptional

Search query to filter posts by content

postTypestring · enumOptional

Filter by post type

Available options:

status, link, photo, gif, video, reel, story, short, poll, document, carousel, article

Possible values:

member_idstringOptional

Filter posts by team member ID

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to retrieve posts from

Responses

200

Successful operation

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

get

/posts

HTTPcURLJavaScriptPython

GET /api/v1/posts HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "posts": [
    {
      "id": "68176f0e8bee9dc9b0ce3427",
      "text": "Check out our new product launch!",
      "url": "https://example.com/product-launch",
      "state": "scheduled",
      "type": "status",
      "account_id": "63c675b54e299e9cf2b667ea",
      "user": {
        "id": "5b1ec026db27977424e8599e",
        "name": "ervintorra",
        "picture": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
      },
      "scheduled_at": "2025-05-15T14:30:00.000+02:00",
      "post_link": "https://facebook.com/post/123456789",
      "has_media": true,
      "network": "facebook"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20,
  "total_pages": 3
}

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 - List social media accounts

• Media API - Upload and manage media for posts

• Create Posts - Post creation endpoints