Configured tool · read-only

`list_posts`

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

read-onlynon-destructiveclosed-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 a connection made with @postdom/mcp@0.4.0 and a workspace-scoped agent key created in Accounts.

Callable schema

Input fields

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

FieldTypeContract

statusOptional

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.

fromOptional

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.

toOptional

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.

accountOptional

string

1 to 255 characters

Keeps only posts targeting one connected account.

limitOptional

integer

1 to 50 · defaults to 20

Caps how many posts one page returns.

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 · statusidentity: The post ID get_publish accepts, and the post's exact feed state.
posts[].scheduled_fordatetime | null: The publish instant in UTC, or null when the post has no publish time.
posts[].caption_previewstring: The caption on one line, cut to 80 characters with an ellipsis when it is longer.
posts[].destinationsarray: Requested account ID, platform, and nullable handle for each destination.
posts[].destinations[].post_urlstring | null: That destination's public URL once it published, and null before then.
posts[].run_urlstring: The Postdom run screen where a human reads what happened to this post.
truncated · posts_total · posts_returnedflag · 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_cursorstring | 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.
windowobject | 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.