GET /segments¶
Use the GET /segments endpoint to return a list of segments from your tenant.
Prerequisites¶
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:
|
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. |