GET /segments

Use the GET /segments endpoint to return a list of segments from your tenant.

Prerequisites

  1. Add an API key.

  2. Generate an access token.

Base URL

Direct all requests to the GET /segments endpoint to the following base URL:

https://{tenant-id}.amperity.com/api/segments/

Rate limit

A rate limit is the number of requests that may be made to the Amperity API in a given time period.

Requests

A request to the GET /segments endpoint is similar to:

curl --request GET \
       'https://tenant.amperity.com/api/segments \
       ?limit=12 \
       ?with_total=true' \
     --header 'amperity-tenant: {tenant}' \
     --header 'api-version: 2024-04-01' \
     --header 'Authorization: Bearer {token}'

(This example is formatted for readability in a narrow page layout.)

Request parameters

The following table describes the parameters that may be used with the GET /segments endpoint.

Parameter

Description

api_version

String. Optional.

A supported version of the Amperity API. For example: 2024-04-01.

Note

You may use the api-version request header instead of the api_version request parameter.

limit

Integer. Optional.

The maximum number of records to include in a single page of results.

next_token

String. Optional.

An opaque token that is used to paginate results. Omit the next_token property to return the first page. Use the cursor value for next_token that was returned in a response to view the next page of results.

For example: ABCd1fghIJk2l3M

Note

The possible values for next_token are returned within the 200 response.

Important

The value for next_token cannot be NULL.

with_total

Boolean. Optional.

Set this value to true to include a total count of all results. Default value: false.

Note

Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set.

Request examples

The following examples show how to send requests to the GET /segments endpoint.

The following example shows how to use cURL to send a request to the GET /segments endpoint.

curl --request GET \
       'https://tenant.amperity.com/api/segments \
       ?limit=12 \
       &with_total=true' \
     --header 'amperity-tenant: {tenant}' \
     --header 'api-version: 2024-04-01' \
     --header 'Authorization: Bearer {token}'

(This example is formatted for readability in a narrow page layout.)

The following example shows how to use Python to send a request to the GET /segments endpoint. This example converts the JSON response into a CSV file named “segments.csv”.

 1import requests
 2import json
 3import csv
 4
 5# URL for Segments endpoint
 6url = "https://tenant-name.amperity.com/api/segments"
 7
 8# Required headers
 9headers = {
10  'accept': 'application/json',
11  'authorization': 'Bearer {token}', # add token here
12  'amperity-tenant': '{tenant}',
13  'api-version': 'version'
14}
15
16# Get the response from the Segments endpoint
17response = requests.request("GET", url, headers=headers, params=payload)
18response_json = response.json()
19
20# Extract headers from the first data entry
21headers = list(response_json["data"][0].keys())
22
23# Specify the output CSV file path
24csv_file_path = "segments.csv"
25
26# Write data to a CSV file
27with open(csv_file_path, mode='w', newline='') as file:
28  writer = csv.DictWriter(file, fieldnames=headers)
29  writer.writeheader()
30  for entry in response_json["data"]:
31    writer.writerow(entry)
32
33print("CSV file generated successfully.")

Responses

A response from the GET /segments endpoint will match an HTTP status code. A 200 response will contain the results set. A 4xx response indicates an issue with the configuration of your request. A 5xx response indicates that the endpoint is unavailable.

200 OK

The 200 response returns a set of segments.

 1{
 2  "total": 0,
 3  "next_token": "ABCa1bcdDEe2f3G",
 4  "data": [
 5    {
 6      "id": "ab-1CDEfGHI",
 7      "name": "Holiday Segment"
 8    },
 9    {
10      "id": "cd-2FGHiJKL",
11      "name": "Returning Customers"
12    }
13  ]
14}

Response parameters

A 200 OK response contains the following parameters.

Parameter

Description

data

A JSON array of values for the current page of results. The array of values includes the following properties:

id

The Amperity internal identifier for the segment.

name

The name of the segment.

next_token

The cursor value to use in a subsequent request to return the next page of results.

Note

When the value for next_token is empty, the last page in the results set has been returned.

total

The total count of all results. This property is only returned when with_total is set to true in a request.

Note

Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set.