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.

cURL

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.)

Python

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”.

import requests
import json
import csv

# URL for Segments endpoint
url = "https://tenant-name.amperity.com/api/segments"

# Required headers
headers = {
  'accept': 'application/json',
  'authorization': 'Bearer {token}', # add token here
  'amperity-tenant': '{tenant}',
  'api-version': 'version'
}

# Get the response from the Segments endpoint
response = requests.request("GET", url, headers=headers, params=payload)
response_json = response.json()

# Extract headers from the first data entry
headers = list(response_json["data"][0].keys())

# Specify the output CSV file path
csv_file_path = "segments.csv"

# Write data to a CSV file
with open(csv_file_path, mode='w', newline='') as file:
  writer = csv.DictWriter(file, fieldnames=headers)
  writer.writeheader()
  for entry in response_json["data"]:
    writer.writerow(entry)

print("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.

{
  "total": 0,
  "next_token": "ABCa1bcdDEe2f3G",
  "data": [
    {
      "id": "ab-1CDEfGHI",
      "name": "Holiday Segment"
    },
    {
      "id": "cd-2FGHiJKL",
      "name": "Returning Customers"
    }
  ]
}

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.