---
updatedAt: 2026-03-30T13:31:48.000Z
agentTools:
  siteIndex: https://documentation.bloomreach.com/llms.txt
  projectIndex: https://documentation.bloomreach.com/engagement/llms.txt
---

# Get catalog items

**/data/v2/projects/{projectToken}/catalogs/{catalogId}/items**

Query catalog for items. You can provide query, sort order, and paging parameters.

Use when you want to retrieve items from an existing catalog.

# Definition

## Authorization

In this API call you must use the following authorization access and permissions:

[block:parameters]
{
  "data": {
    "h-0": "Available access type",
    "h-1": "Permissions needed",
    "0-0": "Private access",
    "0-1": "Catalogs > Get catalog items"
  },
  "cols": 2,
  "rows": 1
}
[/block]

Read more about:

* [Authentication](https://documentation.bloomreach.com/engagement/reference/authentication)
* [Setting up permissions](https://documentation.bloomreach.com/engagement/reference/prerequisites)
* [Creating an authorization header](https://documentation.bloomreach.com/engagement/reference/technical-information)

## Path parameters

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-3": "Required",
    "0-2": "The ID of your project.",
    "0-1": "string",
    "0-0": "projectToken",
    "1-0": "catalogId",
    "1-1": "string",
    "1-2": "The ID of the desired existing catalog.",
    "1-3": "Required"
  },
  "cols": 4,
  "rows": 2
}
[/block]

## Query Parameters

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Example",
    "h-3": "Required",
    "0-0": "query",
    "1-0": "field",
    "0-1": "Query string to match the desired catalog's item properties and item_id.",
    "1-1": "Further refine your query. If used, the query will be matched only against the specified field. \n\n*Works only with indexed catalog columns.*",
    "0-3": "No",
    "1-3": "No",
    "0-2": "?query=Apple",
    "1-2": "&field=manufacturer",
    "2-0": "count",
    "3-0": "skip",
    "4-0": "order",
    "2-3": "No",
    "3-3": "No",
    "4-3": "No",
    "2-1": "How many items should be returned. Default value 20.",
    "2-2": "&count=50",
    "3-1": "How many items should be skipped. Default value 0.\n\n*Count + skip shouldn't be > 1001, otherwise status code 400 will be returned.*",
    "3-2": "&skip=100&count=10",
    "4-1": "By which column and how should be the result ordered.\n\nFormat:\n`column_name`, `desc`/`asc`\n\n*You can add a secondary, tertiary, ...,  column in the same format.*",
    "4-2": "&order=price%20desc,manufacturer%20asc"
  },
  "cols": 4,
  "rows": 5
}
[/block]

[block:callout]
{
  "type": "warning",
  "body": "Please remember that when testing, the `?` should only go before the **first** parameter, and `&` should be used to connect any additional parameters.\ni.e. `?query=apple&field=manufacturer&count=50`",
  "title": "The distinction between `?` and `&`"
}
[/block]

## Header

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "authorization",
    "1-0": "content-type",
    "0-1": "string",
    "0-2": "Used for authentication. Read more in the [Authentication](https://documentation.bloomreach.com/engagement/reference/authentication) section.",
    "0-3": "Required",
    "1-3": "Required",
    "1-2": "application/json",
    "1-1": "string"
  },
  "cols": 4,
  "rows": 2
}
[/block]

# Response description

[block:parameters]
{
  "data": {
    "h-0": "Attribute",
    "h-1": "Type",
    "0-0": "data",
    "0-1": "array of objects",
    "h-2": "Description",
    "0-2": "List of objects representing the individual retrieved rows.",
    "6-0": "success",
    "6-1": "boolean",
    "6-2": "Result status. If false, there is errors object with description.",
    "1-0": "limit",
    "2-0": "matched",
    "3-0": "matched_limited",
    "4-0": "skip",
    "5-0": "total",
    "5-1": "number",
    "5-2": "Total number of items in this catalog.",
    "4-2": "Number of skipped records in this pagination.",
    "2-1": "number",
    "2-2": "Number of items matching the search query.",
    "1-2": "Number of items retrieved in this pagination page.",
    "3-1": "boolean",
    "3-2": "Value is always false. \n\n(Deprecated: If true there were too many items that matched the query, therefore the number of matched items provided above is the lower bound, not the exact number.)",
    "1-1": "number",
    "4-1": "number"
  },
  "cols": 3,
  "rows": 7
}
[/block]

### Data object description

[block:parameters]
{
  "data": {
    "h-0": "Attribute",
    "h-1": "Type",
    "0-0": "catalog_id",
    "0-1": "string",
    "h-2": "Description",
    "0-2": "Catalog unique identifier",
    "1-0": "item_id",
    "2-0": "properties",
    "2-1": "object",
    "2-2": "Actual item fields and values.",
    "1-1": "string",
    "1-2": "Item unique identifier"
  },
  "cols": 3,
  "rows": 3
}
[/block]

# Limitations

You can retrieve only 1001 items using paging. When using count and skip query parameters, count + skip should not be greater than 1001, otherwise, the 404 status code will be returned.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "catalog-api",
    "version": "2"
  },
  "servers": [
    {
      "url": "https://api.exponea.com"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/data/v2/projects/{projectToken}/catalogs/{catalogId}/items": {
      "get": {
        "summary": "Get catalog items",
        "description": "**/data/v2/projects/{projectToken}/catalogs/{catalogId}/items**\n\nQuery catalog for items. You can provide query, sort order, and paging parameters.\n\nUse when you want to retrieve items from an existing catalog.",
        "operationId": "get-catalog-items-2",
        "parameters": [
          {
            "name": "projectToken",
            "in": "path",
            "schema": {
              "type": "string",
              "default": "12345678-1234-1234-1234-123456789abc"
            },
            "required": true
          },
          {
            "name": "catalogId",
            "in": "path",
            "schema": {
              "type": "string",
              "default": "60758e2d18883e1048b817a8"
            },
            "required": true
          },
          {
            "name": "authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "default": "Basic <APIKeyID/APISecret>"
            }
          },
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "Apple"
            }
          },
          {
            "name": "field",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "manufacturer"
            }
          },
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "50"
            }
          },
          {
            "name": "skip",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "100"
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "price%20desc,manufacturer%20asc"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"data\": [\n        {\n            \"catalog_id\": \"60758e2d18883e1048b817a8\",\n            \"item_id\": \"1\",\n            \"properties\": {\n                \"field_date\": 1609455600.0,\n                \"field_number\": 123,\n                \"field_text\": \"Lorem impsum\"\n            }\n        }\n    ],\n    \"limit\": 1,\n    \"matched\": 1113,\n    \"matched_limited\": false,\n    \"skip\": 0,\n    \"success\": true,\n    \"total\": 1113\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "catalog_id": {
                            "type": "string",
                            "example": "60758e2d18883e1048b817a8"
                          },
                          "item_id": {
                            "type": "string",
                            "example": "1"
                          },
                          "properties": {
                            "type": "object",
                            "properties": {
                              "field_date": {
                                "type": "integer",
                                "example": 1609455600,
                                "default": 0
                              },
                              "field_number": {
                                "type": "integer",
                                "example": 123,
                                "default": 0
                              },
                              "field_text": {
                                "type": "string",
                                "example": "Lorem impsum"
                              }
                            }
                          }
                        }
                      }
                    },
                    "limit": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    },
                    "matched": {
                      "type": "integer",
                      "example": 1113,
                      "default": 0
                    },
                    "matched_limited": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "skip": {
                      "type": "integer",
                      "example": 0,
                      "default": 0
                    },
                    "success": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "total": {
                      "type": "integer",
                      "example": 1113,
                      "default": 0
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```