GET /indexes/{id}/profiles

Use the GET /indexes/{id}/profiles endpoint to return a paginated list of customer profiles.

Prerequisites

  1. Add an API key.

  2. Generate an access token.

Base URL

Direct all requests to the GET /indexes/{id}/profiles endpoint to the following base URL:

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

Rate limit

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

The Amperity API supports requests to endpoints that do not exceed a rate of 10 requests per second. Response times will vary by endpoint and the complexity of data that is returned by the response. Some requests may take seconds to return.

Requests to the Amperity API that exceed 10 requests per second may return an error response with an HTTP 429 status code.

Requests

A request to the GET /indexes/{id}/profiles endpoint is similar to:

curl --request GET \
       'https://tenant.amperity.com/api/indexes/{id}/profiles \
       ?limit=100 \
       &with_total=true \
       &filter[<attribute>]=<value>' \
     --header 'amperity-tenant: {tenant}' \
     --header 'api-version: 2025-07-31' \
     --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 /indexes/{id}/profiles endpoint.

Parameter

Description

filter

String. Optional.

One or more index attributes that are configured to be available as filter request properties. Each filter limits the response to include properties that match the attribute and value for each filter.

filter[<attribute>]=<value>

where:

  • [<attribute>] is the name of a field in the index.

  • <value> is the value to be returned in the response.

For example:

filter[first_name]=Daniel

Apply additional filters to the request to narrow the response to return a specific set of profile attributes.

For example, to return a profile for “Daniel Kulhman”:

filter[first_name]=Daniel \
&filter[last_name]=Kulhman

A complete request for “Daniel Kulhman” is similar to:

curl --request GET \
       'https://tenant.amperity.com/api/indexes/{id}/profiles \
       &filter[first_name]=Daniel \
       &filter[last_name]=Kulhman' \
       --header 'amperity-tenant: {tenant}' \
       --header 'api-version: 2025-07-31' \
       --header 'Authorization: Bearer {token}'

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 /indexes/{id}/profiles endpoint.

The following example shows how to use cURL to send a request to the GET /indexes/{id}/profiles endpoint.

curl --request GET \
       'https://tenant.amperity.com/api/indexes/{id}/profiles \
       ?limit=100 \
       &with_total=true \
       &filter[<attribute>]=<value>' \
       --header 'amperity-tenant: {tenant}' \
       --header 'api-version: 2025-07-31' \
       --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 /indexes/{id}/profiles endpoint. This example converts the JSON response into a CSV file named “profiles.csv”.

 1import requests
 2import json
 3import csv
 4
 5# URL for Campaigns endpoint
 6url = "https://tenant-name.amperity.com/api/indexes/{id}/profiles?filter[<attribute>]=<value>"
 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 Profiles 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 = "profiles.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 /indexes/{id}/profiles 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 customer profile indexes.

 1{
 2  "total": 0,
 3  "next_token": "ABCa1bcdDEe2f3G",
 4  "data": [
 5    {
 6      "id": "cl-abc123",
 7      "name": "Loyalty Members",
 8      "created_at": "2025-04-25T20:30:00Z"
 9      "updated_at": "2025-07-26T20:30:00Z"
10    },
11    {
12      "id": "cl-def456",
13      "name": "Online Shoppers",
14      "created_at": "2025-04-25T20:30:00Z"
15      "updated_at": "2025-07-26T20:30:00Z"
16    },
17  ]
18}

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:

created_at

The date and time on which the profile index was created. The date and time must be in RFC3339 format .

id

The Amperity internal identifier for the campaign.

“id”: “cl-def456”, “name”: “Online Shoppers”, “created_at”: “2025-04-25T20:30:00Z” “updated_at”: “2025-07-26T20:30:00Z”

name

The name of the campaign.

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.

updated_at

The date and time on which the profile index was updated. The date and time must be in RFC3339 format .