> Discover all available Postdom documentation from the machine-readable index: https://postdom.com/llms.txt

Configured tool · read-only

# `list_posts`

List this workspace's posts to answer what is scheduled without already holding a post ID.

read-only · non-destructive · closed-world

Human and agent roles

## Configured boundary

### Configured workspace

This read returns one bounded page of the post feed. It cannot create, reschedule, approve, or cancel a post.

This reference describes the hosted server at https://api.postdom.com/mcp, which runs current source, with a workspace-scoped key created under Connected apps → For developers. The published `@postdom/mcp@0.4.0` package has 14 of these tools: it lacks list_posts, create_slideshow, account_music and the media array.

Callable schema

## Input fields

Field names match the configured tool schema. Runtime-only constraints are labeled separately from schema validation.

| Field | Type | Contract |
| --- | --- | --- |
| status Optional | status[] | One to thirteen unique feed statuses Keeps only posts in the listed states; the feed's set adds blocked and unknown to the documented post states. |
| from Optional | datetime | ISO instant · inclusive lower bound on scheduled_for Opens the publish-time window. Resolve a human's local date against the workspace clock first. |
| to Optional | datetime | ISO instant · exclusive upper bound on scheduled_for · must be after from Closes the publish-time window. A post with no publish time is in no window. |
| account Optional | string | 1 to 255 characters Keeps only posts targeting one connected account. |
| limit Optional | integer | 1 to 50 · defaults to 20 Caps how many posts one page returns. |

**For AI agents:** Send only fields exposed by the current tool schema.

**Known failure:** Do not invent platform settings, account IDs, media fields, or setup steps.

Synthetic values

## Example call

Identifiers and values are examples. They do not represent a connected workspace or accepted media source.

_EXAMPLE CALL · CONFIGURED TOOL SCHEMA_

```
list_posts({
  status: ["scheduled", "requires_approval"],
  from: "2026-09-14T00:00:00Z",
  to: "2026-09-21T00:00:00Z"
})
```

Observed API record

## Return shape

Returns a reduced page of posts, whether the page itself was shortened, whether more posts matched, and the window the read was asked for.

**`posts[].id · status` (identity)** — The post ID get_publish accepts, and the post's exact feed state.

**`posts[].scheduled_for` (datetime | null)** — The publish instant in UTC, or null when the post has no publish time.

**`posts[].caption_preview` (string)** — The caption on one line, cut to 80 characters with an ellipsis when it is longer.

**`posts[].destinations` (array)** — Requested account ID, platform, and nullable handle for each destination.

**`posts[].destinations[].post_url` (string | null)** — That destination's public URL once it published, and null before then.

**`posts[].run_url` (string)** — The Postdom run screen where a human reads what happened to this post.

**`truncated · posts_total · posts_returned` (flag · numbers | optional)** — Present only when the page held more posts than the answer could carry. posts_total is what this page held, not what the filters match.

**`next_cursor` (string | null)** — Non-null when more posts match the same filters than this page carried. A different fact from truncated, and both can be set at once.

**`window` (object | null)** — The requested from and to echoed back, or null when no window was asked for.

Stop conditions

## Agent handoff

`posts returned`

### Sort before presenting

The page is taken most-recently-updated first. Order by scheduled_for yourself when the answer is a schedule.

`empty`

### Name the window

Report the echoed window. Nothing matched these filters is not the same claim as nothing is scheduled.

`truncated`

### Say the list is partial

Report posts_returned of posts_total. The answer is bounded by bytes as well as by limit, so a page can come back shorter than limit asked for.

`next_cursor`

### Say more matched

More posts match these filters than this page carried. This tool exposes no cursor input, so narrow the window, statuses, or account rather than presenting the page as the whole set. A null next_cursor means nothing further matched, not that nothing was cut: read truncated for that.

`one post needed`

### Read the record

Use get_publish with the returned ID for the full post, its approval feedback, and every destination attempt.

 VERIFIED · 26 AUGUST 2026  **Configured MCP schema · GET /v1/posts agent post feed**

Examples are synthetic. Human workspace-key creation and revocation remain in Postdom under Connected apps → For developers.