About the Track API

Our Track API provides ways to send real-time customer data to your Customer.io workspace including customer identification and event tracking.

We've generated a Postman collection to help you get started with our APIs.

If you fork this collection, you might want to disable the Watch original collection option. We automatically update our Postman collection whenever we release changes to our documentation, even if we don't change our APIs—which happens daily! Rather than being flooded with Postman notifications, you can check out our Release Notes for updates to our APIs.

NOTE: Postman endpoints default to our US APIs. If you're in our European (EU) region, you'll need to add -eu to the server variables (track_api_url and app_api_url).

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.

Note that if your account is in the EU region and you send traffic to our US endpoints, we'll redirect it accordingly but this traffic still passes through US servers and data could be logged in the US.

Use a private key (sk_) or public key (pk_) as a bearer token: Authorization: Bearer sk_us_.... To route Track API data to destinations outside Customer.io, associate your public or private key with an integration source. Customer.io uses the integration source to determine where to send traffic from the key. If your workspace is configured to route Track API data to destinations outside Customer.io, the Track API rejects requests made with a key that has no integration source (403 Forbidden). When you create a key on the API Credentials page, choose where you'll use the key under Used in. Use a private key on your server and a public key in a browser or mobile app. Learn more about public and private keys.

Legacy credentials: If your integration uses a Site ID and Track API key, you can keep using them with Basic authentication. Each operation on this page lists both kinds of credentials. You can find your Site ID on the API Credentials page. You might also need it to set up in-app messaging in an older version of a mobile SDK.

Most of the time, when we talk about The Track API, we're talking about the v1 API because the v2 API isn't used in any of our libraries and rarely used in libraries built by third parties; it's much more common that you'd encounter the v1 API.

If you're integrating with Customer.io using one of our libraries, or a third party customer data platform (CDP) like Segment or Rudderstack, you'll be using the v1 API.

The v2 API is newer and supports two important features that the v1 API doesn't natively support: objects and batching. But, if you're integrating directly with our API, we suggest you use the Pipelines API. The Pipelines API supports both objects, batching, and all of our newest integrations and libraries are based on it.

The Track API has no fixed rate limit. Customer.io accepts your requests as fast as you send them and doesn't reject or drop them because of volume. Our general guideline is about 3000 requests per 3 seconds, an average of 1000 requests per second. The 3-second window leaves room for short bursts.

Traffic above this level usually comes from high-volume integrations, which our Premium and Enterprise plans support. If your traffic regularly goes above this, we may contact you to learn more about your integration and talk about optimizing it, or about a plan that better suits your volume.

This guideline is subject to change.

Below are the payload size limits for the Track API. If any of these limits are too restrictive for your needs, contact support to let us know your situation as we may be able to accommodate special circumstances.

Customer limits

These limits apply to people and their attributes, often referred to as "customers" in our APIs.

Object and relationship limits

Objects (groups) and relationships between people and objects can have their own attributes. Their limits are similar to people (customers).

Track API Event limits

These limits apply to events that you'll send with the /v1/track call.

v2 API Limits

The v2 API has two endpoints, both of which have limits on the total size of requests.

• /entity is limited to requests 32kb or smaller.

• /batch is limited to requests 500kb or smaller.

  Each of the requests within a batch must also be 32kb or smaller.