---
title: "List catalog snapshots."
method: GET
path: "/v1/catalog/snapshots"
tags: ["Catalog"]
---

# List catalog snapshots.

`GET /v1/catalog/snapshots`

## Request

- Base URL: `https://api.tlmtr.io`
- URL: `https://api.tlmtr.io/v1/catalog/snapshots`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/tlmtr/apis/telemetr-io-public-api/docs/v1/catalog/snapshots/get.ts> (a function with typed inputs; its response is checked against the schema)

Credits keys: 0.001 credits per successful page.

List your active snapshots using cursor pagination. Expired snapshots are excluded.
Returns metadata only, without channel IDs. `active_count` is the total across
all pages; `active_limit` is your current maximum number of active snapshots.
Delete unneeded snapshots or wait for expiration to free capacity.
Use `next_cursor` as `cursor` to request the next page. Page size is 1–1000
(default 100). Catalog and snapshot access must both be enabled.

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

- CatalogSnapshotsResponse
  - `items` CatalogSnapshotResponse[], required: Resource metadata returned on this page.
    - `snapshot_id` string, required: Unique identifier of the original snapshot. Pass it unchanged to snapshot endpoints.
    - `filters` CatalogSnapshotFiltersResponse, required
      - `term` string, nullable: Saved search phrase for channel names; omitted when no phrase is set.
      - `search_in_about` boolean, required: Whether the saved search phrase also matches channel descriptions.
      - `country` string[], required: Saved country identifiers from /v1/dictionaries/countries. An empty list means no country restriction.
      - `language` string[], required: Saved language identifiers from /v1/dictionaries/languages. An empty list means no language restriction.
      - `category` string[], required: Saved category identifiers from /v1/dictionaries/categories. An empty list means no category restriction.
      - `members_min` integer, nullable: Saved minimum channel member count; omitted when unbounded.
      - `members_max` integer, nullable: Saved maximum channel member count; omitted when unbounded.
      - `views_min` integer, nullable: Saved minimum average post views; omitted when unbounded.
      - `views_max` integer, nullable: Saved maximum average post views; omitted when unbounded.
      - `er_min` integer, nullable: Saved minimum engagement rate; omitted when unbounded.
      - `er_max` integer, nullable: Saved maximum engagement rate; omitted when unbounded.
      - `privacy` 'unspecified' | 'public' | 'private'
      - `telegram_verified` boolean, nullable: Saved Telegram verification requirement. True selects verified channels, false selects unverified channels; omitted means no restriction.
    - `channels_count` integer, required: Number of channels saved in the snapshot, up to 800,000.
    - `created_at` string, required: Creation timestamp in UTC, formatted as RFC 3339.
    - `expires_at` string, required: Expiration timestamp in UTC, formatted as RFC 3339. Resources expire 30 days after their own creation.
  - `active_count` integer, required: Total active resources of this type owned by your user, across all pages. For diffs, includes all snapshots even when snapshot_id is specified.
  - `active_limit` integer, required: Maximum active resources of this type allowed by your current API limits. Diff limits apply across all snapshots; reaching the cap blocks creation with HTTP 429.
  - `next_cursor` string, nullable: Opaque token for the next page, or null when no more results remain.

## Other responses

- `400`: Invalid filters, pagination parameters, or cursor.
- `402`: Insufficient credits
- `403`: Catalog and snapshot access must both be enabled.
- `503`: Snapshot storage is temporarily unavailable.

## Changes

- **2026-10-09** `6c2bfd66c5f2`: 4 breaking, 1 info
  - the response's body type changed from `object` to no type for status `402`
  - removed the required property `available_mc` from the response with the `402` status
  - removed the required property `shortfall_mc` from the response with the `402` status
  - removed the required property `total_cost_mc` from the response with the `402` status
  - …1 more
- **2026-09-10** `80951ad7b3fb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tlmtr/apis/telemetr-io-public-api/changes/v1/catalog/snapshots/get.md)

---

[API](https://skmtc.dev/tlmtr/apis/telemetr-io-public-api.md) - [All operations](https://skmtc.dev/tlmtr/apis/telemetr-io-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tlmtr/apis/telemetr-io-public-api/revisions/98f399867856?raw)