View catalog

Beta. The pending_replace block is part of the Beta catalog replace feature. Batch returns it only when a replace session is open for the catalog. Batch also returns it only to callers that send the Batch-Beta: catalog-replace header on API version 2.11 or later.

Use /catalogs/view to view an existing catalog.

View

get

Get information about an existing catalog.

Authorizations

AuthorizationstringRequired

API Key Authentication

Authentication is required in order to interact with Batch's APIs.

Batch implements authentication using API Keys, that we call the "REST API Key". You can find it on your dashboard.

Please make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would easily be extractable.

How to authenticate

In order to authenticate your requests, add your REST API Key in the Authorization header and prefix it by Bearer. Example: Authorization: Bearer bcd38d9rfb38ra28.

Query parameters

namestringRequired

Catalog identifier to retrieve.

indexing_tokenstringOptional

Optional token used for indexing state tracking.

Header parameters

X-Batch-ProjectstringRequired

The unique project key, identifying a project on the Batch platform

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Batch-BetastringOptional

Value of the Batch-Beta header. It is a comma-separated list of Beta contract flags. Thus one request can opt into more than one Beta contract at the same time (first-flag, second-flag). Flags are lowercase and case-sensitive, and the order does not matter. Batch rejects an unknown flag with a 400 on any endpoint. When a contract becomes generally available, Batch continues to accept its flag but the flag has no more effect. Thus you never need to remove it.

Example: catalog-replace

Responses

200

Successfully retrieved the catalog metadata.

application/json

A catalog represents a structured collection of items and associated fields that define the schema of those items.

namestringRequired

Unique identifier for the catalog, used for referencing in API calls.

Example: products

itemsintegerRequired

Total number of items currently stored in this catalog.

Example: 42

sizeintegerRequired

Size of the catalog data in bytes.

Example: 4882372

createdstring · date-timeRequired

RFC 3339 UTC date indicating when the catalog was created.

updatedstring · date-timeRequired

RFC 3339 UTC date of the last update to the catalog.

indexing_statestring · enumOptional

Indicates the current indexing state of the catalog items.

Example: APPLIEDPossible values:

404

Not found

application/json

500

Unexpected error

application/json

503

Batch's services are under maintenance. Please try again later

application/json

get/catalogs/view

GET /2.12/catalogs/view?name=text HTTP/1.1
Host: api.batch.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Batch-Project: text
Accept: */*

{
  "name": "products",
  "fields": [
    {
      "name": "price",
      "type": "float"
    }
  ],
  "items": 42,
  "size": 4882372,
  "created": "2026-01-01T00:00:00.000Z",
  "updated": "2026-01-01T00:00:00.000Z",
  "indexing_state": "APPLIED",
  "pending_replace": {
    "replace_token": "eqRqTF7xFznYoG0MLs1sIqM1JhmhGLTZ7I5NtM5f",
    "indexing_state": "IN_PROGRESS",
    "items": 128,
    "size": 1048576
  }
}

Request structure

Route

The Catalog API exposes a GET endpoint that allows to get information about an existing catalog:

/catalogs/view

Headers and authentication

See Overview → Using Project APIs.

Query parameters

See the API Description.

Responses

Success

If the GET to the API endpoint is successful you will receive an HTTP 200 confirmation and information about your catalog.

{
    "name": "MOVIES",
    "items": 8807,
    "size": 7746977,
    "created": "2025-07-14T16:27:14Z",
    "updated": "2025-07-21T09:20:44Z",
    "fields": [
        {
            "name": "director",
            "type": "string"
        },
        {
            "name": "title",
            "type": "string"
        },
        {
            "name": "release_year",
            "type": "integer"
        },
        {
            "name": "cast",
            "type": "array"
        },
        {
            "name": "description",
            "type": "string"
        }
    ],
    "indexing_state": "APPLIED"
}

The indexing_state is the processing status of updated catalog items that returned the given indexing_token. If there is no indexing token provided, no indexing state will be returned.

2 values are possible for indexing state:

• IN_PROGRESS : catalog item update processing is in progress
• APPLIED : catalog item update processing is finished

While a replace session is open, the response also gives a pending_replace block. Use it to follow the pending revision. It shows you when the revision is ready to complete.

{
    "name": "MOVIES",
    "items": 8807,
    "size": 7746977,
    "created": "2025-07-14T16:27:14Z",
    "updated": "2025-07-21T09:20:44Z",
    "fields": [ { "name": "title", "type": "string" } ],
    "indexing_state": "APPLIED",
    "pending_replace": {
        "replace_token": "eqRqTF7xFznYoG0MLs1sIqM1JhmhGLTZ7I5NtM5f",
        "indexing_state": "IN_PROGRESS",
        "items": 128,
        "size": 1048576
    }
}

The pending_replace block has these fields:

• replace_token : the token that identifies the open replace session.
• indexing_state : the indexing state of the pending revision. It must be APPLIED before you complete the replace.
• items : the number of items in the pending revision now.
• size : the size of the pending revision data, in bytes.

Failure

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at [e-mail] if you need further support.

Reach out to your Customer Success Manager if you need the limits described on this page adjusted for your use case.