GET /collections/{collection-id}/history

Use the GET /collections/{collection-id}/history endpoint to return a bucketed time series of profile counts for a profile collection.

Note

This endpoint is part of the Real-time API, an unstable API that may change without advance notice of breaking changes.

Note

In the Amperity user interface a profile collection is shown on the Profiles page. The value for {collection-id} identifies that profile collection.

Prerequisites

1. Add an API key.

2. Generate an access token.

3. A profile collection must be configured for your tenant. Before creating a profile collection, you must contact your Amperity representative to enable real-time product features.

Note

The access token must be granted the profile-collections:read permission.

Request URL

Direct all requests to the GET /collections/{collection-id}/history endpoint to the request URL. The request URL uses the base URL with the endpoint path appended.

Amazon AWS

https://app.amperity.com/prof/collections/{collection-id}/history

Microsoft Azure

https://{tenant-id}.amperity.com/prof/collections/{collection-id}/history

You can find the tenant ID from the Amperity user interface. From the Settings page and select the Security tab. Under API keys, in the row for an API key, open the menu and select Copy tenant ID.

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 /collections/{collection-id}/history endpoint is similar to:

curl --request GET \
       'https://app.amperity.com/prof/collections/{collection-id}/history?scale=day' \
     --header 'amperity-tenant: {tenant-id}' \
     --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 /collections/{collection-id}/history endpoint.

Parameter	Description
collection-id	String. Required. The ID of the profile collection.
scale	String. Optional. The size of each time bucket. One of minute, hour, or day. Default value: day.
after	Timestamp. Optional. Return buckets at or after this time. When omitted, a default look-back window is used based on the value for scale.
before	Timestamp. Optional. Return buckets at or before this time. When omitted, defaults to the current time.

Responses

A response from the GET /collections/{collection-id}/history endpoint will match an HTTP status code. A 200 response returns the profile-count time series.

200 OK

The 200 response returns the profile-count time series.

{
  "scale": "day",
  "data": [
    {
      "bucket": "{timestamp}",
      "count": 0
    }
  ]
}

Response parameters

A 200 OK response contains the following parameters.

Parameter	Description
scale	The size of each time bucket. One of minute, hour, or day.
data	A JSON array of time buckets. Each item contains a bucket timestamp and the count of profiles for that bucket.

400

The value for after is not before the value for before.