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

# List your posts

`GET /v1/posts`

Retrieve a paginated list of posts from your publication. The publication is identified by the API key provided in the Authorization header.

Use the `status` parameter to filter by post status (published, draft, scheduled, or archived). Defaults to published.

## Query parameters

- `cursor` string
- `limit` integer
- `includeContent` union
  - boolean
  - string
- `status` 'published' | 'draft' | 'scheduled' | 'archived'

## Response `200`

Posts retrieved successfully

- object
  - `items` object[], required — Array of items in this page
    - `id` string, required — Unique identifier for the post
    - `title` string, required — Title of the post
    - `imageUrl` string, uri — Optional URL to the post's main image
    - `imageAlt` string — Alternative text describing the cover image, shown to screen readers and when the image fails to load
    - `publishedAt` string — Epoch timestamp when the post was published
    - `updatedAt` string — Epoch timestamp when the post was last updated
    - `subtitle` string — Optional subtitle or brief summary
    - `slug` string, required — URL-friendly identifier for the post; accessible at paragraph.com/@[publicationSlug]/[slug]
    - `staticHtml` string — Rendered HTML content of the post
    - `json` string — TipTap JSON representation of the post content structure. This is the source of truth that the staticHtml and markdown is generated from
    - `markdown` string — Markdown source of the post content
    - `coinId` string — ID of the associated coin, if the post is coined
    - `categories` string[] — Categories/tags associated with this post
    - `canonicalUrl` string, uri — Canonical URL used in rendered metadata. This does not change the Paragraph permalink.
    - `publishOnline` boolean — Whether the published post is visible on the public website
    - `communityId` string — Subscriber segment id selected for newsletter delivery
    - `authors` object[] — Authors of this post
      - `id` string, required — Unique identifier for the user
      - `walletAddress` string — Wallet address of the user
      - `avatarUrl` string, uri — URL to the user's avatar image
      - `publicationId` string, required — ID of the publication this user belongs to
      - `name` string — Display name of the user
      - `bio` string — Brief biography of the user (max 500 characters)
    - `authorIds` string[] — IDs of the authors of this post
    - `views` number — Total views. Only included when fetching your own posts via GET /v1/posts
    - `status` 'published' | 'draft' | 'scheduled' | 'archived' — Current publish status. Only set on authenticated endpoints (listOwn, getById for your own post). Use this instead of publishedAt to determine publish state — publishedAt is preserved across unpublishing.
  - `pagination` object, required
    - `cursor` string — Cursor for fetching the next page of results
    - `hasMore` boolean, required — Whether more results are available
    - `total` number — Total number of items available

## Other responses

- `401` — Invalid or missing API key
- `500` — Internal server error

## Changes

- **2026-08-28** `8108f2a53d2e` — 3 info
  - added the optional property `items/items/canonicalUrl` to the response with the `200` status
  - added the optional property `items/items/communityId` to the response with the `200` status
  - added the optional property `items/items/publishOnline` to the response with the `200` status
- **2026-08-25** `a38cc07e90d8` — 1 info
  - added the optional property `items/items/imageAlt` to the response with the `200` status
- **2026-08-18** `36c72d74820a` — 1 warning
  - removed the optional property `items/items/authors/items/farcaster` from the response with the `200` status
- **2026-05-07** `90de04b87133` — 2 warning
  - removed the optional property `error` from the response with the `401` status
  - removed the optional property `error` from the response with the `500` status
- **2026-04-17** `b948146fe72f` — 1 info
  - added the optional property `items/items/status` to the response with the `200` status

[Full history](https://skmtc.dev/paragraph-xyz/apis/paragraph-api/changes/v1/posts/get.md)

---

[API](https://skmtc.dev/paragraph-xyz/apis/paragraph-api.md) · [All operations](https://skmtc.dev/paragraph-xyz/apis/paragraph-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/paragraph-xyz/paragraph-api/revisions/8108f2a53d2e/schema)