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

# List catalog snapshot diffs.

`GET /v1/catalog/diffs`

## Request

- Base URL: `https://api.tlmtr.io`
- URL: `https://api.tlmtr.io/v1/catalog/diffs`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/tlmtr/apis/telemetr-io-public-api/docs/v1/catalog/diffs/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 diffs, optionally filtered by `snapshot_id`. Expired diffs are excluded.
`active_count` and `active_limit` apply across all your snapshots, even when the
list is filtered. Delete unneeded diffs or wait for expiration to free capacity.
Use `next_cursor` as `cursor` with the same snapshot filter for the next page.
Page size is 1–1000 (default 100). Catalog and snapshot access must both be enabled.

## Query parameters

- `snapshot_id` string
- `limit` integer
- `cursor` string

## Response `200`

- CatalogSnapshotDiffsResponse
  - `items` CatalogSnapshotDiffResponse[], required: Resource metadata returned on this page.
    - `diff_id` string, required: Unique diff identifier. Pass it unchanged to diff endpoints.
    - `snapshot_id` string, required: Unique identifier of the original snapshot. Pass it unchanged to snapshot endpoints.
    - `added_count` integer, required: Channels matching at diff creation that were absent from the original snapshot.
    - `removed_count` integer, required: Channels in the original snapshot that no longer matched at diff creation. This does not necessarily mean deletion from Telegram.
    - `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/diffs/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)