Send batches of events from your servers to Mixpanel.
Request Format
Each request ingests a batch of events into Mixpanel. We accept up to 2000 events and 2MB uncompressed per request. Events are part of the request body. We support Content-Typeapplication/json或者application/x-ndjson:
[ {"event": "Signup", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4","Referred by": "Friend","URL": "www.jy710.com/signup"}}, {"event": "Purchase", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "935d87b1-00cd-41b7-be34-b9d98dd08b42","Item": "Coffee", "Amount": 5.0}} ]{"event": "Signup", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4","Referred by": "Friend","URL": "www.jy710.com/signup"}} {"event": "Purchase", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "935d87b1-00cd-41b7-be34-b9d98dd08b42","Item": "Coffee", "Amount": 5.0}}We also support内容编码：GZIPto reduce network egress.
Authentication
/导入需要所有者或管理员Service Account. project_id, service account username and service account password are required to authenticate a request.
注意： /导入也支持项目秘密出于遗产原因。如果您不指定project_id，我们将使用秘密验证。
Validation
/import validates the supplied events and returns a 400 status code if任何of the events fail validation with details of the error. If some events pass validation and others fail, we will ingest the events that pass validation. When you encounter a 400 error in production, simply log the JSON response, as it will contain the$ insert_ids of the invalid events, which can be used to debug.
High-level requirements
- Each event must be properly formatted JSON.
- Each event must contain an event name, time, distinct_id, and $insert_id. These are used to deduplicate events, so that this endpoint can be safely retried.
- Each event must be smaller than 1MB of uncompressed JSON.
- Each event must have fewer than 255 properties.
- 所有嵌套对象属性必须少于255个键，而最大嵌套深度为3。
- All array properties must have fewer than 255 elements.
事件的示例
{ "event": "Signed up", "properties": { "time": 1618716477000, "distinct_id": "91304156-cafc-4673-a237-623d1129c801", "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4", "ip": "136.24.0.114", "Referred by": "Friend", "URL": "www.jy710.com/signup", } }
event
This is the name of the event. If you're loading data from a data warehouse, we recommend using the name of the table as the name of the event.
We recommend keeping the number of unique event names relatively small and using properties for any variable context attached to the event. For example, instead of tracking events with names "Paid Signup" and "Free Signup", we would recommend tracking an event called "Signup" and having a property "Account Type" with value "paid" or "free".
特性
This is a JSON object representing all the properties about the event. If you're loading data from a data warehouse, we recommend using column names as the names of properties.
特性.time
The time at which the event occurred, in seconds or milliseconds since epoch. We require a value for time. We will reject events with time values that are before 1971-01-01 or more than 1 hour in the future as measured on our servers.
特性.distinct_id
distinct_id identifies the user who performed the event. distinct_id must be specified on every event, as it is crucial for Mixpanel to perform behavioral analysis (unique users, funnels, retention, cohorts) correctly and efficiently.
If the event is not associated with any user, set distinct_id to the empty string. Events with an empty distinct_id will be excluded from all behavioral analysis.
To prevent accidental implementation mistakes, we disallow the following values for distinct_id:
- 00000000-0000-0000-0000-000000000000 - anon - anonymous - nil - none - null - n/a - na - undefined - unknown - - 0 - -1 - true - false - [] - {}
特性.$insert_id
We require that $insert_id be specified on every event. $insert_id provides a unique identifier for the event, which we use for deduplication. Events with identical values for (event, time, distinct_id, $insert_id) are considered duplicates and only one of them will be surfaced in queries.
$ insert_ids must be ≤ 36 bytes and contain only alphanumeric characters or "-". We also disallow any value for $insert_id from the list of invalid IDs provided for distinct_id above.
Example of a validation error
{ "code": 400, "error": "some data points in the request failed validation", "failed_records": [ { "index": 0, "$insert_id": "8a66058c-a56d-4ef6-8123-28b7c9f7e82f", "field": "properties.time", "message": "properties.time' is invalid: must be specified as seconds since epoch" }, { "index": 3, "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4", "field": "properties.utm_source", "message": "properties.utm_source is invalid: string should be valid utf8" }, ], "num_records_imported": 23, "status": "Bad Request" }When any single event in the batch does not pass validation, we return a 400 status code and a response that looks like the above.
failed_recordsincludes one row for each of the failed events, with details about the error we found. If some of the rows passed validation, we will ingest them and return their count innum_records_imported.
GeoIP Enrichment
If you supply a propertyipwith an IP address, Mixpanel will automatically do a GeoIP lookup and replace theipproperty with geographic properties (City, Country, Region). These properties can be used in our UI to segment events geographically.
This is an example of an event before and after enrichment:
{ "event": "Signed up", "properties": { "time": 1618716477000, "distinct_id": "91304156-cafc-4673-a237-623d1129c801", "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4", "ip": "136.24.0.114", "Referred by": "Friend", "URL": "www.jy710.com/signup", } }{ "event": "Signed up", "properties": { "time": 1618716477000, "distinct_id": "91304156-cafc-4673-a237-623d1129c801", "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4", "Referred by": "Friend", "URL": "www.jy710.com/signup", "$city": "San Francisco", "$region": "California", "mp_country_code": "US" } }
Rate Limits
To ensure real-time ingestion and quality-of-service, we have a rate limit of 2GB of uncompressed JSON/minute or ~30k events per second, measured on a rolling 1 minute basis.
We recommend the following when it comes to sending data to our API at scale:
- Send data as quickly as possible with concurrent clients until the server returns 429. We see the best results with 10-20 concurrent clients sending 2K events per batch.
- When you see 429s, employ an抖动的指数退缩strategy. We recommend starting with a backoff of 2s and doubling backoff until 60s, with 1-5s of jitter.
- We recommend gzip compression and using
内容编码：GZIPto reduce network egress and transfer time. - 在极少数情况下，我们的API返回502或503状态代码，我们建议采用与429s相同的指数退回策略。
- Please do not retry validation errors (400 status code), as they will consistently fail and count toward the rate limit.
If you are an enterprise customer and require a higher limit for a 1-time backfill, please reach out to your sales representative with your project_id and use-case.
常见问题
所有事件都需要$ insert_id。这使得重试 /进口请求是安全的。如果您的事件尚未具有唯一的ID（例如：A UUID/GUID），我们建议计算一组属性的哈希，这些属性使事件在语义上唯一（例如：Distract_id + Timestamp +其他属性）并使用该哈希作为$ insert_id的前36个字符。
We truncate all strings down to 255 characters. Here's what we recommend for the various cases in which this typically happens:
- URLs: We recommend parsing the URL and tracking its individual components (host, path, url params) as properties. This is more useful in analysis, as you can segment events by hostname or a particular URL parameter.
- JSON encoded strings: Sometimes a long string may be a JSON object encoded as a string. We recommend parsing the JSON and flattening it into properties to send with the event. This is similarly much more useful in analysis, as you can filter or breakdown by any key within the JSON.
- 免费文本 /用户生成的内容：一些长字段可能包括全文（例如：搜索词或注释）。如果此属性对分析不起作用，我们建议将其从跟踪到Mixpanel排除在外，以避免意外发送任何PII。
Guides
请参阅我们的云摄入指南，例如使用此API以集成Google Pub/Sub,Amazon S3, orGoogle Cloud Storage.