HTTP API

Send event data from source to destination using our HTTP API.

  •   11 minute read  

This guide provides a complete reference for the RudderStack HTTP API.

Overview

RudderStack offers an easy-to-use HTTP API that you can use to send your events programmatically. The API is fully Segment-compatible and is helpful in cases where you cannot use the SDKs.

RudderStack recommends using the RudderStack SDKs for tracking and routing user events from your sources. The SDKs offer automatic tagging of user context, event batching, and a retry functionality during delivery failure.

To use the HTTP API, configure an HTTP source in the dashboard, then send POST requests to your data plane URL via the v1/<event_type> endpoints.

If the client cannot send POST requests (for example, HTML/CSS-only UIs), use the Pixel API with the same HTTP source write key instead.

Prerequisites

Source information
  • Download (Right click > Save Link As) and import the Postman collection in this URL. Then, edit the variables source_write_key and data_plane_urlwith your write key and data plane URL

Authorization

RudderStack uses Basic Authentication for authenticating all HTTP requests.

If you’re using Postman, authenticate the API by including an empty string ("") as the username and your source write key as the password in the Authorization tab.

To send events via the RudderStack HTTP API, set the Content-Type header to application/json.

Base URL

Use the data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL at the top of the Connections page in your RudderStack dashboard. as the base URL for your API requests.

Identify

The identify call lets you associate a visiting user to their actions and record any associated traits.

POST /v1/identify

Sample payload

json
{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "context": {
    "traits": {
       "trait1": "new-val"  
    },
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

bash
curl -u <source_write_key>: -X POST <data_plane_url>/v1/identify \
-d @identify.json \
--header "Content-Type: application/json"

Accepted fields

anonymousId
optional
string
Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.
userId
required, if anonymousId is not present
string
Unique identifier for a particular user in your database.
context
optional
object
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
optional
object
A dictionary containing the destinations to be either enabled or disabled.
timestamp
optional
datetime
The timestamp of the message’s arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For example: 2022-02-01T19:14:18.381Z
traits
optional
object
Dictionary of the traits associated with the user, such as nameor email

Track

The track call lets you track user actions along with any properties associated with them.

POST /v1/track

Sample payload

json
{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "event": "Product Purchased new",
  "properties": {
    "name": "Shirt",
    "revenue": 4.99
  },
  "traits": {
    "email": "alex@example.com"
  },
  "context": {
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

bash
curl -u <source_write_key>: -X POST <data_plane_url>/v1/track \
-d @track.json \
--header "Content-Type: application/json"

Accepted fields

anonymousId
optional
string
Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.
userId
required, if anonymousId is not present
string
Unique identifier for a particular user in your database.
context
optional
object
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
event
required
string
Name of the event being performed by the user.
properties
optional
object
Dictionary of the properties associated with a particular event.
traits
optional
object
Explicitly specified user traits. Note that:

  • The client-side SDKs automatically add this object persisted from the identify event.
  • Any traits specified in the track event will override the existing traits persisted from the identify event.
  • The override will be applicable only for the particular track event where the traits object is specified explicitly. For future events, the user traits persisted from the identify event are used.
integrations
optional
object
A dictionary containing the destinations to be either enabled or disabled.
timestamp
optional
datetime
The timestamp of the message’s arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For example: 2022-02-01T19:14:18.381Z

Page

The page call lets you record your website’s page views with any additional relevant information about the viewed page.

POST /v1/page

Sample payload

json
{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "name": "Page View",
  "properties": {
    "title": "Home",
    "path": "/"
  },
  "context": {
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

bash
curl -u <source_write_key>: -X POST <data_plane_url>/v1/page \
-d @page.json \
--header "Content-Type: application/json"

Accepted fields

anonymousId
optional
string
Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.
userId
required, if anonymousId is not present
string
Unique identifier for a particular user in your database.
context
optional
object
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
optional
object
A dictionary containing the destinations to be either enabled or disabled.
name
required
string
Name of the page being viewed.
properties
optional
object
Dictionary of the properties associated with a particular event.
timestamp
optional
datetime
The timestamp of the message’s arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For example: 2022-02-01T19:14:18.381Z

Screen

The screen call is the mobile equivalent of the page call. It lets you record whenever your user views their mobile screen with any additional relevant information about the screen.

POST /v1/screen

Sample payload

json
{
  "userId": "identified user id",
  "anonymousId":"anon-id-new",
  "name": "Screen View",
  "properties": {
    "prop1": "5"
  },
  "context": {
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-02-02T00:23:09.544Z"
}

Usage

bash
curl -u <source_write_key>: -X POST <data_plane_url>/v1/screen \
-d @screen.json \
--header "Content-Type: application/json"

Accepted fields

anonymousId
optional
string
Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.
userId
required, if anonymousId is not present
string
Unique identifier for a particular user in your database.
context
optional
object
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
optional
object
A dictionary containing the destinations to be either enabled or disabled.
name
required
string
Name of the screen being viewed.
properties
optional
object
Dictionary of the properties associated with the page being viewed, such as url and referrer.
timestamp
optional
datetime
The timestamp of the message’s arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For example: 2022-02-01T19:14:18.381Z

Group

The group call lets you link an identified user with a group such as a company, organization, or an account. It also lets you record any custom traits associated with that group, like the name of the company, the number of employees, etc.

POST /v1/group

Sample payload

json
{
  "userId": "user123",
  "groupId": "group1",
  "traits": {
    "name": "Company",
    "industry": "Industry",
    "employees": 123
  },
  "context": {
    "traits": {
       "trait1": "new-val"  
    },
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-01-21T00:21:34.208Z"
}

Usage

bash
curl -u <source_write_key>: -X POST <data_plane_url>/v1/group \
-d @group.json \
--header "Content-Type: application/json"

Accepted fields

anonymousId
optional
string
Sets the user ID for cases where there is no unique identifier for the user. Either userId or anonymousId is required.
userId
required, if anonymousId is not present
string
Unique identifier for a particular user in your database.
context
optional
object
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
optional
object
A dictionary containing the destinations to be either enabled or disabled.
groupId
required
string
Unique identifier of the group, as present in your database.
traits
optional
object
Dictionary of the traits associated with the group, such as nameor email
timestamp
optional
datetime
The timestamp of the message’s arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For example: 2022-02-01T19:14:18.381Z

Alias

The alias call lets you merge different identities of a known user.

alias is an advanced method that lets you change the tracked user’s ID explicitly. This method is useful when managing identities for some of the downstream destinations.
POST /v1/alias

Sample payload

json
{
  "userId": "user123",
  "previousId": "previd1",
  "context": {
    "traits": {
       "trait1": "new-val"  
    },
    "ip": "14.5.67.21",
    "library": {
        "name": "http"
    }
  },
  "timestamp": "2020-01-21T00:21:34.208Z"
}

Usage

bash
curl -u <source_write_key>: -X POST <data_plane_url>/v1/alias \
-d @alias.json \
--header "Content-Type: application/json"

Accepted fields

userId
required, if anonymousId is not present
string
Unique identifier for a particular user in your database.
context
optional
object
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
optional
object
A dictionary containing the destinations to be either enabled or disabled.
previousId
required
string
The previous unique identifier of the user.
traits
optional
object
Dictionary of the traits associated with the group, such as nameor email
timestamp
optional
datetime
The timestamp of the message’s arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For example: 2022-02-01T19:14:18.381Z

Batch

The batch call allows you to send a series of identify, track, page, group and screen requests in a single batch. This call helps you minimize the number of outbound requests, thus enabling better performance.

RudderStack sets a maximum limit of 4 MB per batch request and 32 KB per call.
POST /v1/batch

Sample payload

json
{
    "batch": [{
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "type": "identify",
            "context": {
                "traits": {
                    "trait1": "new-val"
                },
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "event": "Product Purchased new",
            "type": "track",
            "properties": {
                "name": "Shirt",
                "revenue": 4.99
            },
            "context": {
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "name": "Page View",
            "type": "page",
            "properties": {
                "title": "Home",
                "path": "/"
            },
            "context": {
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "identified user id",
            "anonymousId": "anon-id-new",
            "name": "Screen View",
            "type": "screen",
            "properties": {
                "prop1": "5"
            },
            "context": {
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-02-02T00:23:09.544Z"
        },
        {
            "userId": "user123",
            "type": "group",
            "groupId": "group1",
            "traits": {
                "name": "Company",
                "industry": "Industry",
                "employees": 123
            },
            "context": {
                "traits": {
                    "trait1": "new-val"
                },
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-01-21T00:21:34.208Z"
        },
        {
            "userId": "user123",
            "previousId": "previd1",
            "type":"alias",
            "context": {
                "traits": {
                    "trait1": "new-val"
                },
                "ip": "14.5.67.21",
                "library": {
                    "name": "http"
                }
            },
            "timestamp": "2020-01-21T00:21:34.208Z"
        }

    ]
}

Usage

bash
curl -u <source_write_key>: -X POST <data_plane_url>/v1/batch \
-d @batch.json \
--header "Content-Type: application/json"

Accepted fields

batch
required
array
An array of identify, track, page, group and screen calls. Each call must have a type property and a valid method name.

HTTP responses

Status code
Description
200Successful API request
400Bad request — possible reasons include:

401Missing or invalid authorization header

Make sure that the source write key and the basic authentication header is valid.
404Source or destination is disabled
413Request body is too large
429Too many requests
500Internal server error

Maximum allowed request size

RudderStack allows messages with a maximum size of 32 KB per call. The batch endpoint accepts a maximum call size of 4 MB per batch, and 32 KB per call. RudderStack responds with a 400 Bad Request error if these limits are exceeded.

Maximum allowed JSON nesting depth

RudderStack accepts event JSON payloads with a maximum nesting depth of 200 levels. Events that exceed this limit are rejected during ingestion with error feedback returned to the sender.

The following example highlights how JSON nesting depth is calculated. Both objects and arrays count toward the nesting depth:

json
{
  "a": [
    {
      "b": {
        "c": "This JSON has a nesting depth of 4"
      }
    }
  ]
}

In this example, the array a is at depth 1, the object inside the array is at depth 2, the object b is at depth 3, and the field c is at depth 4.

Event ordering

To maintain event ordering while using the HTTP API, make sure to include sentAt and anonymousId as a header in every request.

Event ordering

Historical imports

RudderStack lets you import any historical data by simply adding the timestamp argument to any of your API calls. However, this can be done only for the destinations that accept historical time-stamped data, like Amplitude, Mixpanel, etc.

If you are tracking current events, leave out the timestamp field. RudderStack will automatically add the timestamps to the event requests.

Questions? Let's figure it out together.

Join the RudderStack Slack community to connect with other users, customers, and the RudderStack team — or reach out for direct support.

Slack community Join now Email support Reach out