---
title: "List your posts"
method: GET
path: "/posts"
tags: ["Posts"]
---

# List your posts

`GET /posts`

## Request

- Base URL: `https://www.juzpost.com/api/cli/v1`
- URL: `https://www.juzpost.com/api/cli/v1/posts`
- Auth: HTTP bearer

Returns posts newest first by default, with the post-level fields only. Per-account
delivery state lives on `GET /posts/{postId}`. Note that `from` and `to` filter on
creation time, not on the scheduled publish time. Sorting by `scheduledFor` silently
excludes posts that have no scheduled time, since unscheduled drafts have nothing to
sort on. Cursor-paginated.

## Query parameters

- `limit` integer
- `cursor` string
- `order` 'asc' | 'desc'
- `sort` 'createdAt' | 'scheduledFor'
- `status` string
- `accountId` string, uuid
- `from` string, date-time
- `to` string, date-time

## Response `200`

One page of posts.

- PostPage: A page of posts.
  - `data` PostListItem[], required: The posts in this page.
    - `id` string, uuid, required: The post id.
    - `status` string, required: Coarse lifecycle summary such as `draft`, `scheduled`, `posted` or `failed`. It is a rollup hint, not authoritative per account. Read `targets` on the detail endpoint to know what each account actually did.
    - `type` 'text' | 'image' | 'video' | 'story' | 'blog', required: What kind of content the post carries. Anything other than `text` and `blog` must have at least one media key before it can be scheduled. `blog` is a WordPress blog post: `title` is required and `description` is the body, HTML sent as written (plain text works, blank lines become paragraphs). The first image is the featured image and any others are added under the body. Images only.
    - `title` string, nullable, required: The title stored in the post's metadata, or null if none was set.
    - `content` string, required: The post body or caption. Empty string when the post has none.
    - `mediaUrls` string[], required: Storage keys of the post's media, as returned by `POST /storage/presign`. Empty when the post has no media.
    - `scheduledFor` string, date-time, nullable, required: The post-level scheduled fire time, or null if the post is not scheduled. Individual accounts may have their own times that differ from this.
    - `coverR2Key` string, nullable, required: Storage key of the cover image, or null if none was set.
    - `createdAt` string, date-time, required: When the post was created.
    - `updatedAt` string, date-time, required: When the post was last modified.
  - `pagination` PaginationMeta, required: Page state returned by every list operation. Keyset-based, so it stays correct while rows are being inserted, and it deliberately carries no total count.
    - `limit` integer, required: The page size actually applied, after clamping to 1-100.
    - `nextCursor` string, nullable, required: Pass this back as the `cursor` query parameter to fetch the next page. It is `null` when there is no next page.
    - `hasMore` boolean, required: True when at least one more page exists. Stop paginating when this is false rather than when the data array is short.

## Other responses

- `400`: The request body or query string failed validation. `error.message` names the first problem found.
- `401`: No bearer token was sent, or the token is unknown, revoked or malformed. Run the device login again to obtain a new token.
- `402`: The plan behind this token does not include the capability this operation needs. `error.details.requiredPlan` names the tier that does. This is never a token problem, so do not retry without changing the plan.

---

[API](https://skmtc.dev/juzpost/apis/juzpost-rest-api.md) · [All operations](https://skmtc.dev/juzpost/apis/juzpost-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/juzpost/apis/juzpost-rest-api/revisions/19296da24f95?raw)