Skip to content

list_posts

Returns posts in the workspace — scheduled, draft, published, and failed — newest first, with per-target delivery state so an agent can tell which profile actually received a post. Paginated, with counts per status alongside.

On this page
  1. Parameters
  2. Example request
  3. Response
Category
Publishing
REST
POST/api/tools/list_posts

Parameters

status
enumoptional
all · scheduled · published · draft · failed · processingdefault: all
page
numberoptional
1-based page number.default: 1
limit
numberoptional
Posts per page.default: 9
all
booleanoptional
Return every matching post in one response, ignoring pagination.
workspaceId
stringoptional
Workspace to act on, from list_workspaces. Omit to use the default workspace on the key.

Example request

curl -X POST "https://api.postmcpai.com/api/tools/list_posts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $POSTMCPAI_API_KEY" \
  -d '{
    "status": "failed",
    "limit": 20
  }'

Response

posts[] with targets[] carrying the per-profile outcome — the remote postId on success, or error on failure — plus pagination and counts.

200 · application/json
{
  "posts": [
    {
      "id": "66a50b12e4b019a2b71c",
      "content": "Building social automation with PostMCP AI 🤖",
      "platforms": [
        "linkedin",
        "twitter"
      ],
      "targets": [
        {
          "platform": "linkedin",
          "profileId": "lin_9823412",
          "username": "alex-johnson-dev",
          "status": "published",
          "postId": "urn:li:share:7218..."
        },
        {
          "platform": "twitter",
          "profileId": "tw_1293847",
          "username": "@alexj_dev",
          "status": "failed",
          "error": "Duplicate content rejected by upstream"
        }
      ],
      "status": "published",
      "scheduleDate": "2026-08-01",
      "scheduleTime": "14:30",
      "timezone": "Asia/Kolkata",
      "mediaUrl": "https://postmcpai.com/uploads/demo.png",
      "createdAt": "2026-07-30T10:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 9,
    "totalPosts": 34,
    "totalPages": 4
  },
  "counts": {
    "all": 34,
    "scheduled": 11,
    "published": 21,
    "failed": 2
  }
}