HTTP Tracking API

The Segment HTTP Tracking API lets you record analytics data from any website or application. The requests hit our servers, and we route your data to any integration you want!

We have native sources for most use cases (Javascript, iOS, etc.) that are all built for high-performance and are open-source. But sometimes you may want to send to the HTTP API directly—that’s what this reference is for.

Headers

Authentication

Tracking API requests are sorted by a source’s Write Key, which must be sent with each request using HTTP Basic Auth.

Basic Auth base64 encodes a 'username:password' and prepends it with the string 'Basic '.

The Basic Auth username should be the Write Key and the password should be left empty.

If a Segment source’s Write Key is 'abc123', the final result of the should be 'Basic YWJjMTIzOg=='.

This is passed in the authorization header like so 'Authorization: Basic YWJjMTIzOg=='.

Content-Type

In order to send data to our HTTP API, a content-type header must be set to 'application/json'.

Errors

We currently return a 200 response for all API requests so debugging should be done in the Segment Debugger. The only exception is if the request is too large / json is invalid it will respond with a 400.

We’re hard at work surfacing more errors and more helpful responses to our users. If you have any suggestions, let us know or kick off a conversation in the Segment Community.

Rate Limits

There is no hard rate limit at which point Segment will drop your data. However, to avoid processing delays we ask customers to send requests at a maximum rate of 50 requests per second. Requests include batches sent with the batch method, which means you can send a large batch of events inside of a single request. If you need to import at a faster rate please contact us first.

Identify

identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them.

We recommend calling identify a single time when the user’s account is first created, and only identifying again later when their traits change.

Example identify call:

POST https://api.segment.io/v1/identify
{
  "userId": "019mr8mf4r",
  "traits": {
    "email": "pgibbons@initech.com",
    "name": "Peter Gibbons",
    "industry": "Technology"
  },
  "context": {
    "ip": "24.5.68.47"
  },
  "timestamp": "2012-12-02T00:30:08.276Z"
}

This call is identifying the user by his unique User ID (the one you know him by in your database) and labeling him with email, name, and industry traits.

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier

See the Identities docs for more detail

context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale

See the Context field docs for more detail

integrations optionalObjectDictionary of integrations to either enable or disable

See the Integrations field docs for more detail

timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API

It is an ISO-8601 date string

If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp.See the Timestamps fields docs for more detail.

traits optionalObjectFree-form dictionary of traits of the user, like email or name.

See the Traits field docs for a list of reserved trait names

userId requiredStringUnique identifier for the user in your database

A userId or anonymousId is required

See the Identities docs for more detail

Find details on the identify method payload in our Spec.

Track

track lets you record the actions your users perform.Every action triggers what we call an “event”, which can also have associated properties.

You’ll want to track events that are indicators of success for your site, like Signed Up, Item Purchased or Article Bookmarked.

To get started, we recommend tracking just a few important events. You can always add more later!

Example track call:

POST https://api.segment.io/v1/track
{
  "userId": "019mr8mf4r",
  "event": "Item Purchased",
  "properties": {
    "name": "Leap to Conclusions Mat",
    "revenue": 14.99
  },
  "context": {
    "ip": "24.5.68.47"
  },
  "timestamp": "2012-12-02T00:30:12.984Z"
}

track event properties can be anything you want to record. In this case, name and revenue.

The track call has the following fields:

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier

See the Identities docs for more detail

context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale

See the Context field docs for more detail

event requiredStringName of the action that a user has performed.

See the Event field docs for more detail

integrations optionalObjectDictionary of integrations to either enable or disable

See the Integrations field docs for more detail

properties optionalObjectFree-form dictionary of properties of the event, like revenue

See the Properties docs for a list of reserved property names

timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API

It is an ISO-8601 date string

If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp.See the Timestamps fields docs for more detail.

userId requiredStringUnique identifier for the user in your database

A userId or anonymousId is required

See the Identities docs for more detail

Find details on best practices in event naming as well as the track method payload in our Spec.

Page

The page method lets you record page views on your website, along with optional extra information about the page being viewed.

Example page call:

POST https://api.segment.io/v1/page
{
  "userId": "019mr8mf4r",
  "name": "Tracking HTTP API",
  "timestamp": "2012-12-02T00:31:29.738Z"
}

The page call has the following fields:

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier

See the Identities docs for more detail

context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale

See the Context field docs for more detail

integrations optionalObjectDictionary of integrations to either enable or disable

See the Integrations field docs for more detail

name optionalStringName of the page

For example, most sites have a “Signup” page that can be useful to tag, so you can see users as they move through your funnel.

properties optionalObjectFree-form dictionary of properties of the page, like url and referrer

See the Properties field docs for a list of reserved property names

timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API

It is an ISO-8601 date string

If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp.See the Timestamps fields docs for more detail.

userId requiredStringUnique identifier for the user in your database

A userId or anonymousId is required

See the Identities docs for more detail

Find details on the page payload in our Spec.

Screen

The screen method let you record whenever a user sees a screen of your mobile app.

You’ll want to send the screen message whenever a user requests a page of your app.

Example screen call:

POST https://api.segment.io/v1/screen
{
  "userId": "019mr8mf4r",
  "name": "Tracking HTTP API",
  "timestamp": "2012-12-02T00:31:29.738Z"
}

The screen call has the following fields:

_
anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier

See the Identities docs for more detail

context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale

See the Context field docs for more detail

integrations optionalObjectDictionary of integrations to either enable or disable

See the Integrations field docs for more detail

name optionalStringName of the screen

See the Name field docs for more detail

properties optionalObjectFree-form dictionary of properties of the screen, like name

See the Properties field docs for a list of reserved property names

timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API

It is an ISO-8601 date string

If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp.See the Timestamps fields docs for more detail.

userId requiredStringUnique identifier for the user in your database

A userId or anonymousId is required

See the Identities docs for more detail

Find details on the screen payload in our Spec.

Group

group lets you associate an identified user with a group. A group could be a company, organization, account, project or team! It also lets you record custom traits about the group, like industry or number of employees.

This is useful for tools like Intercom, Preact and Totango, as it ties the user to a group of other users.

Example group call:

POST https://api.segment.io/v1/group
{
  "userId": "019mr8mf4r",
  "groupId": "8e9df332ac",
  "traits": {
    "name": "Initech",
    "industry": "Technology",
    "employees": 420
  },
  "timestamp": "2012-12-02T00:31:38.208Z"
}

The group call has the following fields:

anonymousId optionalStringA pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier

See the Identities docs for more detail

context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale

See the Context field docs for more detail

groupId requiredStringA unique identifier for the group in your database.

See the Group ID field docs for more detail

integrations optionalObjectDictionary of integrations to either enable or disable

See the Integrations field docs for more detail

timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API

It is an ISO-8601 date string

If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp.See the Timestamps fields docs for more detail.

traits optionalOjbectFree-form dictionary of traits of the group, like email or name

See the Traits field docs for a list of reserved trait names

userId requiredStringUnique identifier for the user in your database

A userId or anonymousId is required

See the Identities docs for more detail

Find more details about group including the group payload in our Spec.

Alias

alias is how you associate one identity with another. This is an advanced method, but it is required to manage user identities successfully in some of our integrations.

In Mixpanel it’s used to associate an anonymous user with an identified user once they sign up. For KISSmetrics, if your user switches IDs, you can use ‘alias’ to rename the ‘userId’.

Example alias call:

POST https://api.segment.io/v1/alias
{
  "previousId": "39239-239239-239239-23923",
  "userId": "019mr8mf4r",
  "timestamp": "2012-12-02T00:31:29.738Z"
}

The alias call has the following fields:

context optionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale

See the Context field docs for more detail

integrations optionalObjectDictionary of integrations to either enable or disable

See the Integrations field docs for more detail

previousId requiredStringPrevious unique identifier for the user

See the Previous ID field docs for more detail

timestamp optionalDateTimestamp when the message itself took place, defaulted to the current time by the Segment Tracking API

It is an ISO-8601 date string

If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp.See the Timestamps fields docs for more detail.

userId requiredStringUnique identifier for the user in your database

A userId or anonymousId is required

See the Identities docs for more detail

For more details on the alias call and payload, check out our Spec.

Historical Import

You can import historical data by adding the timestamp argument to any of your method calls. This can be helpful if you’ve just switched to Segment.

Historical imports can only be done into integrations that can accept historical timestamp’ed data. Most analytics tools like Mixpanel, Amplitude, Kissmetrics, etc. can handle that type of data just fine. One common integration that does not accept historical data is Google Analytics since their API cannot accept historical data.

Note: If you’re tracking things that are happening right now, leave out the timestamp and our servers will timestamp the requests for you.

Batch

The batch method lets you send a series of identify, group, track, page and screen requests in a single batch, saving on outbound requests. Our server-side and mobile sources make use of this method automatically for higher performance.

There is a maximum of 500kb per batch request and 32kb per call.

Here’s the what the batch request signature looks like:

POST https://api.segment.io/v1/batch
{
  "batch": [
    {
      "type": "identify",
      "userId": "019mr8mf4r",
      "traits": {
        "email": "jake@yahoo.com",
        "name": "Jake Peterson",
        "age": 26
      },
      "timestamp": "2012-12-02T00:30:08.276Z"
    },
    {
      "type": "track",
      "userId": "019mr8mf4r",
      "event": "Song Played",
      "properties": {
        "name": "Fallin for You",
        "artist": "Dierks Bentley"
      },
      "timestamp": "2012-12-02T00:30:12.984Z"
    },
    {
      "type": "identify",
      "userId": "971mj8mk7p",
      "traits": {
        "email": "cindy@gmail.com",
        "name": "Cindy Gonzalez",
        "age": 23
      },
      "timestamp": "2015-2-02T00:30:08.276Z"
    },
    {
      "type": "track",
      "userId": "971mj8mk7p",
      "event": "Song Played",
      "properties": {
        "name": "Get Right",
        "artist": "Jennifer Lopez"
      },
      "timestamp": "2015-2-02T00:30:12.984Z"
    }
  ],
  "context": {
    "device": {
      "type": "phone",
      "name": "Apple iPhone 6"
    }
  }
}
batch ArrayAn array of identify, group, track, page and screen method calls. Each call must have an type property with a valid method name.
context Object, optionalThe same as Context for other calls, but it will be merged with any context inside each of the items in the batch.
integrations Object, optionalThe same as Integrations for other calls, but it will be merged with any integrations inside each of the items in the batch.

Selecting Integrations

The alias, group, identify, page and track calls can all be passed an object of integrations that lets you turn certain integrations on or off. By default all integrations are enabled.

Here’s an example showing an identify call that only goes to Mixpanel and KISSmetrics:

POST https://api.segment.io/v1/identify
{
  "userId": "019mr8mf4r",
  "traits": {
    "email": "pgibbons@initech.com",
    "name": "Peter Gibbons",
    "industry": "Technology"
  },
  "context": {
    "ip": "24.5.68.47"
  },
  "timestamp": "2012-12-02T00:30:08.276Z",
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "KISSmetrics": true,
    "Google Analytics": false
  }
}

In this case, we’re specifying that we want this identify to only go to Mixpanel and KISSmetrics. 'All': false says that no integration should be enabled unless otherwise specified. 'Mixpanel': true turns on Mixpanel, etc.

Integration flags are case sensitive and match the integration’s name in the docs (i.e. “AdLearn Open Platform”, “awe.sm”, “MailChimp”, etc.).

Note:

  • Available at the business level, filtering track calls can be done right from the Segment UI on your source schema page. We recommend using the UI if possible since it’s a much simpler way of managing your filters and can be updated with no code changes on your side.

  • If you are on a grandfathered plan, events sent server-side that are filtered through the Segment dashboard will still count towards your API usage.

Collecting IP Address

When sending a HTTP call from a user’s device, you can collect the IP address by setting context.direct to true.

Troubleshooting

If you’re having trouble we have a few tips that help common problems.

No events in my debugger

  1. Double check that you’ve followed all the steps in the Quickstart.

  2. Make sure that you’re calling one of our API methods once the library is successfully installed—identify, track, etc.

No events in my end tools

  1. Double check your credentials for that integration.

  2. Make sure that the integration you are troubleshooting can accept server-side API calls. Compatibility is shown on the integration docs pages and on the sheets on your Segment source Integrations page.

  3. Check out the integration’s documentation to see if there are other requirements for using the method and integration you’re trying to get working.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!