---
title: "List content groups"
method: GET
path: "/v1/buckets"
tags: ["buckets"]
---

# List content groups

`GET /v1/buckets`

## Request

- Base URL: `https://public.api.paragraph.com/api`
- URL: `https://public.api.paragraph.com/api/v1/buckets`
- Auth: HTTP bearer

Retrieve the content groups in your publication, most recently active first. The publication is identified by the API key.

A group ("bucket") is one identity for a post and everything made out of it — the post, the X thread drawn from it, the LinkedIn version, the newsletter. It's what the writer sees as a single stacked row under Content.

Each group lists its members in display order, with the post it was seeded from first. Bodies aren't included; fetch the member with `GET /v1/content/{id}` or `GET /v1/posts/{id}` to read one.

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

Content groups retrieved successfully

- object
  - `items` object[], required: Array of items in this page
    - `id` string, required: Unique identifier for this bucket
    - `title` string, required: What the group is called, taken from the post that seeded it
    - `createdAt` string, required: ISO 8601 timestamp of creation
    - `updatedAt` string, required: ISO 8601 timestamp of the last change to the group
    - `members` object[], required: The pieces in this group, in display order — the post it was seeded from first
      - `kind` 'post' | 'content' | 'other', required: What `id` addresses: `post` reads with `GET /v1/posts/{id}`, `content` with `GET /v1/content/{id}`, and `other` can't be read through this API
      - `id` string, required: Identifier of the piece itself
      - `channel` string, required: Where this piece is meant to go: `post`, `tweet`, `linkedin`, `newsletter`, `x_article`, or `other`
      - `title` string, nullable, required: What the piece is called, or null when it has no name yet
      - `status` 'draft' | 'published' | 'archived', nullable, required: Whether the piece has been delivered, is still a draft, or was archived. Null for a member this API can't read.
      - `scheduled` boolean, required: Whether a scheduled send is queued against this piece
      - `url` string, nullable, required: Where this piece went live, or null when it hasn't been delivered. Also null by design for a channel that publishes no page.
      - `publishedAt` string, nullable, required: ISO 8601 timestamp of the first delivery, or null
      - `archivedAt` string, nullable, required: ISO 8601 timestamp of when this piece was archived, or null
      - `position` integer, required: Display order inside the bucket. The post the group was seeded from is always 0.
      - `updatedAt` string, required: ISO 8601 timestamp of the last change to the piece itself, not to its grouping
  - `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
- `404`: Publication not found
- `500`: Internal server error

## Changes

- **2026-09-01** `2d43a4d31af2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/paragraph-xyz/apis/paragraph-api/changes/v1/buckets/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.dev/paragraph-xyz/apis/paragraph-api/revisions/c148c610fb95?raw)