---
title: "List social posts"
method: POST
path: "/api/social/posts/list"
tags: ["Social"]
---

# List social posts

`POST /api/social/posts/list`

## Request

- Base URL: `https://app.pedra.ai`
- URL: `https://app.pedra.ai/api/social/posts/list`
- Auth: none required

Returns the account's posts sorted by scheduledAt, newest first, optionally filtered by status, network and a scheduledAt range. Use it to see what went out (`platformPostId`) and why anything failed (`error`). Pedra Pro only. Free.

## Request body

- object
  - `apiKey` string, required: Account API key, sent in the request body. Get one at https://app.pedra.ai under Settings → API.
  - `status` 'pending' | 'processing' | 'posted' | 'failed' | 'cancelled': pending: waiting for its time (only pending posts can be cancelled). processing: being published. posted: live on the network. failed: not published, see error. cancelled: cancelled before it went out.
  - `network` 'instagram' | 'facebook' | 'tiktok' | 'youtube': A supported social network.
  - `from` string, date-time: Only posts with scheduledAt at or after this time.
  - `to` string, date-time: Only posts with scheduledAt at or before this time.
  - `limit` integer

## Response `200`

The posts.

- object
  - `posts` SocialPost[]
    - `postId` string, required: Pedra's id for the post.
    - `network` 'instagram' | 'facebook' | 'tiktok' | 'youtube', required: A supported social network.
    - `status` 'pending' | 'processing' | 'posted' | 'failed' | 'cancelled', required: pending: waiting for its time (only pending posts can be cancelled). processing: being published. posted: live on the network. failed: not published, see error. cancelled: cancelled before it went out.
    - `scheduledAt` string, date-time, required: When the post is due, in UTC.
    - `postedAt` string, date-time, nullable, required: When it went out, or null.
    - `platformPostId` string, nullable, required: The network's id once posted (e.g. the YouTube video id). For private TikTok posts, the publish id.
    - `videoId` string, required: The stored video, shared by all posts from the same call.
    - `error` string, nullable, required: Why the post failed, or null.
    - `firstCommentError` string: Only present when a Facebook first comment failed. The post itself still went out.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The account isn't on Pedra Pro.
- `405`: Wrong HTTP method; these endpoints accept POST only.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/pedra/apis/pedra-api.md) · [All operations](https://skmtc.dev/pedra/apis/pedra-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pedra/apis/pedra-api/revisions/87b2e76912c8?raw)