Search label assignments (GET)

Searches label assignments across entities using label or entity filters. Returns a paginated list of matching assignments.

Example request

curl -X GET "https://{host}/api_gateway/v2/labels/assignments/search?entityType=PRODUCT&labelName=Summer+Sale&limit=10&offset=0" \
  -H "Authorization: Bearer {token}"

Prerequisites

Requires authentication with a valid bearer token.
The token must have read access to the Labels resource.

Resource information


Pagination support	Yes
Batch support	No

Query parameters

Field	Type	Required	Description
`entityType`	enum	Required	Entity type to search assignments for. One of: `CUSTOMER`, `PRODUCT`, `STORE`.
`labelId`	integer	Conditional	System-assigned label identifier. At most one of `labelId`, `labelName`, or `labelExternalId` may be provided.
`labelName`	string	Conditional	Display name of the label. At most one of `labelId`, `labelName`, or `labelExternalId` may be provided.
`labelExternalId`	string	Conditional	Caller-defined label identifier. At most one of `labelId`, `labelName`, or `labelExternalId` may be provided.
`entityId`	string	Optional	Filter results to a single entity identifier.
`limit`	integer	Optional	Number of results to return per page. Between 1 and 50. Defaults to `10`.
`offset`	integer	Optional	Number of results to skip. Minimum 0. Defaults to `0`.

Example response

{
  "data": [
    {
      "entityId": "SKU-001",
      "labelId": 101,
      "labelName": "Summer Sale",
      "labelExternalId": "SUMMER_SALE",
      "expiryDate": "2026-08-31"
    }
  ],
  "pagination": {
    "totalCount": 1,
    "limit": 10,
    "offset": 0
  },
  "errors": []
}

Response parameters

Field	Type	Description
`data`	array	Matching assignment records.
`.entityId`	string	Entity identifier.
`.labelId`	integer	System-assigned identifier of the label.
`.labelName`	string	Display name of the label.
`.labelExternalId`	string	Caller-defined identifier of the label, or null if not set.
`.expiryDate`	string	Expiry date in `YYYY-MM-DD` format, or null if the assignment does not expire.
`pagination`	object	Pagination metadata.
`.totalCount`	integer	Total number of assignments matching the filters.
`.limit`	integer	Maximum number of results returned in this response.
`.offset`	integer	Number of results skipped before this page.
`errors`	array	Any errors encountered during the search.

Error and warning codes

Code	Error number	Type	Description
`LABEL_INVALID_ENTITY_TYPE`	23006	Error	`entityType` is not one of `CUSTOMER`, `PRODUCT`, `STORE`. HTTP 400.
`ASSIGNMENT_INVALID_LIMIT`	23046	Error	`limit` is outside the range 1–50. HTTP 400.
`ASSIGNMENT_INVALID_OFFSET`	23047	Error	`offset` is negative. HTTP 400.