List segments

List

get

List segments

Authorizations

rest_key

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

fromstringOptional

A cursor for pagination accross multiple pages of results. Don't include this parameter on the first call. Use the next_from value returned in a previous response to request subsequent resutls.

limitinteger · max: 100Optional

A limit on the number of objects to be returned.

Default: 10Example: 20

Header parameters

X-Batch-ProjectstringRequired

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

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Responses

200

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

application/json

countintegerOptional

The total number of objects.

Example: 48

has_morebooleanOptional

Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Example: true

next_fromstringOptional

A cursor for use in pagination. If has_more is true, you can pass the value of next_from to a subsequent call to fetch the next page of resutls.

Example: U0VHRU1FTlQtQ09ERUAyMDI2LTAxLTAxVDAwOjAwOjAwWg==

400

The request is malformed

application/json

401

The Rest API Key is not valid for this project

application/json

429

Too Many Requests

application/json

500

Unexpected error

application/json

503

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

application/json

get

/segments/list

HTTPcURLJavaScriptPython

GET /2.11/segments/list HTTP/1.1
Host: api.batch.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Batch-Project: text
Accept: */*

{
  "segments": [
    {
      "code": "SEGMENT-CODE",
      "display_name": "Segment name",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "count": 48,
  "has_more": true,
  "next_from": "U0VHRU1FTlQtQ09ERUAyMDI2LTAxLTAxVDAwOjAwOjAwWg=="
}

Request structure

Route

The segment API exposes a GET endpoint that allows you to list all segments :

/segments/list

Headers and authentication

See Overview → Using Project APIs.

Responses

Success

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

{
  "segments": [
    {
      "code": "SEGMENT-CODE",
      "display_name": "Segment name",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "count": 48,
  "has_more": true,
  "next_from": "U0VHRU1FTlQtQ09ERUAyMDI2LTAxLTAxVDAwOjAwOjAwWg=="
}

If your export request returns no data, the files array will be empty.

Pagination infos:

• next_from can be used for the next call to list to retrieve the next page

• count is the number of items in the current page

Failure

If the GET data does not meet the API requirements you will receive an actionable error message. Contact us at [email protected] if you need further support.

See the list of potential failures in the API Description.