Go to website

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
Query parameters
stateanyOptional

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

fromanyOptional

Filter posts scheduled/published after this date

  • Example: 2025-05-15

Required if to is provided

toanyOptional

Filter posts scheduled/published before this date

  • Example: 2025-05-15

Required if from is provided

pageanyOptional

Page number for pagination

account_idsanyOptional

Filter posts by multiple account IDs

queryanyOptional

Search query to filter posts by content

postTypeanyOptional

Filter by post type

Available options:

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

member_idanyOptional

Filter posts by team member ID

Header parameters
Publer-Workspace-IdanyRequired

ID of the workspace to retrieve posts from

Responses
200
Successful operation
application/json
get
GET /api/v1/posts HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
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

PreviousAccountsNextMedia

Last updated

Was this helpful?