--- title: "Create catalog snapshot." method: POST path: "/v1/catalog/snapshots" tags: ["Catalog"] --- # Create catalog snapshot. `POST /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: (a function with typed inputs; its response is checked against the schema) Save the set of channels matching the supplied catalog filters at creation time. Returns metadata and the channel count, without channel IDs. The saved filters are reused when creating diffs; search sorting and pagination do not apply. The maximum matching-channel count comes from your current API plan or Subscription key settings and is capped by the datastore ceiling. Larger results return 422 `SNAPSHOT_TOO_LARGE` rather than being truncated. Snapshots expire after 30 days; storage is included in the creation price. Credits keys: 0.400 credits per successful creation, with no additional base or per-channel fee. Every POST creates and bills a new resource; creation does not deduplicate retries. After a timeout, inspect existing resources before sending another POST. Your active snapshot cap is returned as `active_limit` by List snapshots. Reaching it returns 429 `SNAPSHOT_LIMIT_REACHED`. Only one snapshot creation per user can run at a time; concurrent requests return 429 `SNAPSHOT_CREATION_IN_PROGRESS`. Retry temporary conflicts after `Retry-After`. Catalog and snapshot access must both be enabled for your API credentials. ## Request body - CreateSnapshotBody - `filters` CatalogFilters, required - `term` string, nullable: Search phrase in channel name. Minimum 3 characters (1 for Chinese) - `search_in_about` boolean: Search in channel description. `term` will be searched not only in the channel name but also in the description - `country` string, nullable: Channel country. List of countries can be obtained here `/v1/dictionaries/countries` - `language` string, nullable: Channel language. List of languages can be obtained here `/v1/dictionaries/languages` - `category` string, nullable: Channel category id. List of categories can be obtained here `/v1/dictionaries/categories` Example: `mf2MkrwoE` - `members_min` integer, nullable: Minimum members count - `members_max` integer, nullable: Maximum members count - `views_min` integer, nullable: Minimum average post views - `views_max` integer, nullable: Maximum average post views - `er_min` integer, nullable: Minimum engagement rate - `er_max` integer, nullable: Maximum engagement rate - `privacy` 'Public' | 'Private': Channel privacy type - `verified_only` boolean: Only Telegram verified channels ## Response `201` Snapshot created - CatalogSnapshotResponse - `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. ## Other responses - `400`: Invalid filters, pagination parameters, or cursor. - `402`: Insufficient credits - `403`: Catalog and snapshot access must both be enabled. - `422`: Matching catalog set exceeds max_channels returned in the error. Narrow the filters. - `429`: Active resource limit reached or a conflicting operation is in progress. Inspect code; honor Retry-After for temporary conflicts. - `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/post.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)