Skip to main content
GET
/
public
/
v1
/
posts
List Posts
curl --request GET \
  --url https://api.example.com/public/v1/posts
{
  "400": {},
  "401": {},
  "posts": [
    {
      "id": "<string>",
      "group": "<string>",
      "publishDate": "<string>",
      "status": "<string>",
      "content": "<string>",
      "integration": {},
      "media": [
        {}
      ],
      "settings": {}
    }
  ]
}

​
Overview

Retrieve a list of posts within a specified date range. Returns scheduled, published, and draft posts with their content, media, and status.

​
Request

​
Query Parameters

​
startDate
string
required
ISO 8601 date string for the start of the date range.Example: 2024-01-01T00:00:00Z
​
endDate
string
required
ISO 8601 date string for the end of the date range.Example: 2024-12-31T23:59:59Z
​
customer
string
Optional customer ID to filter posts for a specific customer (multi-tenant scenarios).

​
Response

​
posts
array
Array of post objects

​
Examples

curl -X GET "https://api.postiz.com/public/v1/posts?startDate=2024-01-01T00:00:00Z&endDate=2024-12-31T23:59:59Z" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Response Example

{
  "posts": [
    {
      "id": "post-123",
      "group": "group-abc",
      "publishDate": "2024-12-31T12:00:00Z",
      "status": "scheduled",
      "content": "Hello from Postiz!",
      "integration": {
        "id": "integration-456",
        "name": "Twitter (@myaccount)",
        "identifier": "twitter",
        "picture": "https://pbs.twimg.com/profile.jpg"
      },
      "media": [
        {
          "id": "media-789",
          "url": "https://cdn.postiz.com/image.jpg",
          "type": "image"
        }
      ],
      "settings": {
        "who_can_reply_post": "everyone"
      }
    },
    {
      "id": "post-124",
      "group": "group-abc",
      "publishDate": "2024-12-31T12:00:00Z",
      "status": "scheduled",
      "content": "Hello from Postiz!",
      "integration": {
        "id": "integration-457",
        "name": "LinkedIn (John Doe)",
        "identifier": "linkedin",
        "picture": "https://media.licdn.com/profile.jpg"
      },
      "media": [],
      "settings": {
        "visibility": "public"
      }
    }
  ]
}

​
Filtering by Status

While the API doesn’t provide a status query parameter, you can filter posts client-side: 
const result = await postiz.postList({
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-12-31T23:59:59Z'
});

// Filter scheduled posts only
const scheduledPosts = result.posts.filter(post => 
  post.status === 'scheduled'
);

// Filter failed posts
const failedPosts = result.posts.filter(post => 
  post.status === 'failed'
);

// Filter by platform
const twitterPosts = result.posts.filter(post => 
  post.integration.identifier === 'twitter'
);

​
Default Date Range

The CLI uses default date ranges if not specified:
  • Start Date: 30 days ago from today
  • End Date: 30 days from today
This covers both recent posts and upcoming scheduled posts.

​
Pagination

The current API returns all posts within the date range. For large datasets, consider:
  1. Using smaller date ranges
  2. Filtering by customer for multi-tenant applications
  3. Implementing client-side pagination

​
Error Responses

​
400
Bad Request
Invalid date format or missing required parameters
{
  "statusCode": 400,
  "message": ["startDate must be a valid ISO 8601 date string"],
  "error": "Bad Request"
}
​
401
Unauthorized
Invalid or missing API key
{
  "msg": "Invalid API key"
}

​
Notes

Posts are grouped by the group identifier. Multiple posts with the same group ID represent a multi-platform post created in a single request.
Use reasonable date ranges to avoid large responses. A 3-6 month range is typically optimal for most use cases.

​
Next Steps

Create Post

Schedule a new post

Delete Post

Delete a scheduled post

Build docs developers (and LLMs) love

Get started for freeTalk to us