required | value must be: `$identify` | +| **properties** | Object
required | | +| **properties.distinct_id** | String
optional | The distinct ID post-identification (same as $identified_id - it will be inferred from $identified_id if not included) | +| **properties.$identified_id** | String
required | A distinct_id to merge with the $anon_id. | +| **properties.$anon_id** | String
required | A distinct_id to merge with the $identified_id. The $anon_id must be [UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier) format and not already merged to an $identified_id. | +| **properties.token** | String
required | The project token. | diff --git a/reference/Identity API/identities/identity-create-alias.md b/reference/Identity API/identities/identity-create-alias.md index fee01623ce..badca72a12 100644 --- a/reference/Identity API/identities/identity-create-alias.md +++ b/reference/Identity API/identities/identity-create-alias.md @@ -1,52 +1,86 @@ --- -title: "Create Alias" -slug: "identity-create-alias" -excerpt: "" -hidden: false -createdAt: "2021-08-04T20:46:15.948Z" -updatedAt: "2023-09-26T21:06:37.385Z" +title: Create Alias +category: + uri: Identity API +content: + excerpt: '' +privacy: + view: public --- +
| Event Object property | +Type | +Description | +
|---|---|---|
| **event** | + +
+ String required + |
+
+ value must be: `$create_alias` |
+
| **properties** | + +
+ Object required + |
+
+ + |
| **properties.distinct\_id** | + +
+ String required + |
+
+ A distinct\_id to be merged with the alias. | +
| **properties.alias** | + +
+ String required + |
+
+ A new distinct\_id to be merged with the original distinct\_id. Each alias can only map to one distinct\_id. | +
| **properties.token** | + +
+ String required + |
+
+ The project token. | +
| Event Object property | +Type | +Description | +
|---|---|---|
| **event** | +
+ String required + |
+ A name for the event. For example, "Signed up", or "Uploaded Photo". | +
| **properties** | +
+ Object required + |
+ + |
| **properties.distinct\_id** | +
+ String required + |
+ The value of `distinct_id` will be treated as a string, and used to uniquely identify a user associated with your event. If you provide a distinct\_id property with your events, you can track a given user through funnels and distinguish unique users for retention analyses. You should always send the same distinct\_id when an event is triggered by the same user. | +
| **properties.token** | +
+ String required + |
+ The Mixpanel token associated with your project. You can find your Mixpanel token in the project settings dialog in the Mixpanel app. Events without a valid token will be ignored. | +
| **properties.time** | +
+ String required + |
+ The time an event occurred. If present, the value should be a unix timestamp (seconds since midnight, January 1st, 1970 - UTC). If this property is not included in your request, Mixpanel will use the time the event arrives at the server. | +
| **properties.$insert\_id** | +
+ String required + |
+ A unique UUID tied to exactly one occurrence of an event. | +
+ +## Important Notes + +**Raw Event Export** - Deduplication is not applied to raw data exports. If you export events via the API, you may see duplicates. It is recommended to apply the same deduplication logic (event name, distinct\_id, timestamp, $insert\_id) to your exported data + +**Insert ID Best Practice** - Always generate a unique $insert\_id for each event. Reusing $insert\_id (e.g., setting it to the user’s distinct\_id) can cause unintended deduplication and data loss + +**Deduplication Timing** - Query-time deduplication is immediate. Compaction-time deduplication timing is not guaranteed and may take hours to days to complete.s diff --git a/reference/Ingestion API/events/import-events.md b/reference/Ingestion API/events/import-events.md index fe1b007058..7676e746c7 100644 --- a/reference/Ingestion API/events/import-events.md +++ b/reference/Ingestion API/events/import-events.md @@ -1,11 +1,12 @@ --- -title: "Import Events" -slug: "import-events" -hidden: false -createdAt: "2020-10-20T00:41:26.243Z" -updatedAt: "2023-09-26T21:06:38.671Z" +title: Import Events +category: + uri: Ingestion API +content: + excerpt: '' +privacy: + view: public --- - Use this API to send batches of events from your servers to Mixpanel. ## Request Format @@ -29,21 +30,22 @@ We also support `Content-Encoding: gzip` to reduce network egress. ## Authentication - `/import` requires an Owner or Admin [Service Account](https://developer.mixpanel.com/reference/service-accounts). project_id, service account username, and service account password are required to authenticate a request. + `/import` requires an Owner or Admin [Service Account](https://developer.mixpanel.com/reference/service-accounts). project\_id, service account username, and service account password are required to authenticate a request. -`/import` also supports [Project Token](https://developer.mixpanel.com/reference/project-token) as an authentication method. You can provide your token as the basic auth username value with an empty password. If project_id is not specified, the request will be authenticated using the provided token. +`/import` also supports [Project Token](https://developer.mixpanel.com/reference/project-token) as an authentication method. You can provide your token as the basic auth username value with an empty password. If project\_id is not specified, the request will be authenticated using the provided token. ## Validation + If you provide the `strict=1` parameter (recommended), `/import` will validate the supplied events and return a 400 status code if **any** of the events fail validation with details of the error. If some events pass validation and others fail, Mixpanel 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_id`s 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. -- All nested object properties must have fewer than 255 keys and a max nesting depth is 3. -- All array properties must have fewer than 255 elements. +* 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. +* All nested object properties must have fewer than 255 keys and a max nesting depth is 3. +* All array properties must have fewer than 255 elements. ### Example of an event @@ -60,23 +62,30 @@ If you provide the `strict=1` parameter (recommended), `/import` will validate t } } ``` + #### 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 the value "paid" or "free". #### properties + 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. ##### 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. -##### properties.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 time value is set in the future, it will be overwritten with the current present time at ingestion. + +##### properties.distinct\_id -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. +`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. -To prevent accidental implementation mistakes, we disallow the following values for distinct_id: +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 @@ -98,10 +107,11 @@ To prevent accidental implementation mistakes, we disallow the following values - {} ``` -##### properties.$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. +##### properties.$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. +$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 @@ -170,25 +180,29 @@ This is an example of an event before and after enrichment: ``` ## Rate Limit -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. + +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 [exponential backoff with jitter](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) 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 `Content-Encoding: gzip` to reduce network egress and transfer time. -- In the rare event that our API returns a 502 or 503 status code, we recommend employing the same exponential backoff strategy as with 429s. -- Please do not retry validation errors (400 status code), as they will consistently fail and count toward the rate limit. +* 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 [exponential backoff with jitter](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) 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 `Content-Encoding: gzip` to reduce network egress and transfer time. +* In the rare event that our API returns a 502 or 503 status code, we recommend employing the same exponential backoff strategy as with 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. +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. ## Common Issues -`$insert_id` is required on all events. This makes it safe to retry `/import` requests. If your events don't already have a unique ID (eg: a UUID/GUID), we recommend computing a hash of some set of properties that make the event semantically unique (eg: distinct_id + timestamp + some other property) and using the first 36 characters of that hash as the $insert_id. + +`$insert_id` is required on all events. This makes it safe to retry `/import` requests. If your events don't already have a unique ID (eg: a UUID/GUID), we recommend computing a hash of some set of properties that make the event semantically unique (eg: distinct\_id + timestamp + some other property) and using the first 36 characters of that hash as the $insert\_id. 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. -- Free text / user generated content: Some long fields may include full-text (eg: a search term or a comment). If this property isn't useful for analysis, we recommend excluding it from tracking to Mixpanel to avoid accidentally sending over any PII. + +* 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. +* Free text / user generated content: Some long fields may include full-text (eg: a search term or a comment). If this property isn't useful for analysis, we recommend excluding it from tracking to Mixpanel to avoid accidentally sending over any PII. ## Guides + See our Cloud Ingestion guides for example usage of this API to integrate with [Google Pub/Sub](https://docs.mixpanel.com/docs/tracking-methods/integrations/google-pubsub), [Amazon S3](https://docs.mixpanel.com/docs/tracking-methods/integrations/amazon-s3), or [Google Cloud Storage](https://docs.mixpanel.com/docs/tracking-methods/integrations/google-cloud-storage). diff --git a/reference/Ingestion API/events/track-event.md b/reference/Ingestion API/events/track-event.md index 5e0bb4ea4b..2ac56ceb68 100644 --- a/reference/Ingestion API/events/track-event.md +++ b/reference/Ingestion API/events/track-event.md @@ -1,31 +1,31 @@ --- -title: "Track Events" -slug: "track-event" -excerpt: "" -hidden: false -createdAt: "2021-07-27T00:06:02.814Z" -updatedAt: "2023-09-26T21:06:38.693Z" +title: Track Events +category: + uri: Ingestion API +content: + excerpt: '' +privacy: + view: public --- - Track events to Mixpanel from client devices. We recommend using one of our client-side SDKs instead of using /track directly, as our SDKs provide queueing, retrying, batching, and more. ## When to use /track vs /import Typically, we recommend using /import for server-side integrations as it is more scalable and supports ingesting historical data. We only recommend /track for client-side tracking in an environment for which we don't have SDK support or if you're sending data via some other untrusted environment (eg: third-party webhooks that send data to Mixpanel). -| | /track | /import | -| --------------------------- | ---------------------------------------------- | ----------------------------------------------------- | -| Events per request | 2000 | 2000 | -| Authentication | Project Token, intended for untrusted clients. | Project Secret/Service Accounts, intended for server-side integration. | -| Compression | Gzip allowed | Gzip allowed | -| Content-Type | application/x-www-form-urlencoded | application/json or application/x-ndjson | -| Ingesting historical events | Last 5 days only. | Any time after 1971-01-01. | +| | /track | /import | +| --------------------------- | ---------------------------------------------- | --------------------------------------------------------------------- | +| Events per request | 2000 | 2000 | +| Authentication | Project Token, intended for untrusted clients. | Project Secret/Service Account, intended for server-side integration. | +| Compression | Gzip allowed | Gzip allowed | +| Content-Type | application/x-www-form-urlencoded | application/json or application/x-ndjson | +| Ingesting historical events | Last 5 days only. | Any time after 1971-01-01. | ## Limits The limits for track are the same as /import, [see here](https://developer.mixpanel.com/reference/import-events#rate-limits). -Each line of event has the following size limits: +Each event has the following size limits: - Must be smaller than 1MB of uncompressed JSON. - Must have fewer than 255 properties. @@ -42,4 +42,4 @@ We recommend the following when it comes to sending data to our API at scale: - In the rare event that our API returns a 502 or 503 status code, we recommend employing the same exponential backoff strategy as with 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 that requires a higher rate limit, please reach out to your CSM with your project_id and use case. +If you are an Enterprise customer that requires a higher rate limit, please reach out to your CSM with your `project_id` and use case. diff --git a/reference/Ingestion API/group-profiles.md b/reference/Ingestion API/group-profiles.md deleted file mode 100644 index 473d4f082a..0000000000 --- a/reference/Ingestion API/group-profiles.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Group Profiles" -slug: "group-profiles" -hidden: false -createdAt: "2020-10-20T00:41:25.536Z" -updatedAt: "2023-09-26T21:06:38.596Z" ---- diff --git a/reference/Ingestion API/group-profiles/_order.yaml b/reference/Ingestion API/group-profiles/_order.yaml new file mode 100644 index 0000000000..e2d71f6b16 --- /dev/null +++ b/reference/Ingestion API/group-profiles/_order.yaml @@ -0,0 +1,8 @@ +- group-set-property +- group-set-property-once +- group-delete-property +- group-remove-from-list-property +- group-union +- group-batch-update +- delete-group +- limits-1 diff --git a/reference/Ingestion API/group-profiles/delete-group.md b/reference/Ingestion API/group-profiles/delete-group.md index 58931edc8b..1095591cb6 100644 --- a/reference/Ingestion API/group-profiles/delete-group.md +++ b/reference/Ingestion API/group-profiles/delete-group.md @@ -1,8 +1,10 @@ --- -title: "Delete Group" -slug: "delete-group" -excerpt: "Deletes a group profile from Mixpanel." -hidden: false -createdAt: "2020-10-20T00:41:26.265Z" -updatedAt: "2023-09-26T21:06:39.053Z" +title: Delete Group +category: + uri: Ingestion API +content: + excerpt: Deletes a group profile from Mixpanel. +privacy: + view: public --- + diff --git a/reference/Ingestion API/group-profiles/group-batch-update.md b/reference/Ingestion API/group-profiles/group-batch-update.md index 8d7b155e0c..5c5eb9bbde 100644 --- a/reference/Ingestion API/group-profiles/group-batch-update.md +++ b/reference/Ingestion API/group-profiles/group-batch-update.md @@ -1,8 +1,17 @@ --- -title: "Batch Update Group Profiles" -slug: "group-batch-update" -excerpt: "Send a batch of group profile updates. Instead of sending a single JSON object as the data query parameter, send a JSON list of objects as the data parameter of an application/x-www-form-urlencoded POST or GET request body" -hidden: false -createdAt: "2021-04-15T17:31:51.660Z" -updatedAt: "2023-09-26T21:06:39.041Z" +title: Batch Update Group Profiles +category: + uri: Ingestion API +content: + excerpt: >- + Send a batch of group profile updates. Instead of sending a single JSON + object as the data query parameter, send a JSON list of objects as the data + parameter of an application/x-www-form-urlencoded POST or GET request body. + + + Refer to the respective group profile update commands ($set, $set_once, + $add, $union, $remove, $unset, and $delete) on syntax for their parameters. +privacy: + view: public --- + diff --git a/reference/Ingestion API/group-profiles/group-delete-property.md b/reference/Ingestion API/group-profiles/group-delete-property.md index 3814de90b1..8121345689 100644 --- a/reference/Ingestion API/group-profiles/group-delete-property.md +++ b/reference/Ingestion API/group-profiles/group-delete-property.md @@ -1,8 +1,10 @@ --- -title: "Delete Property" -slug: "group-delete-property" -excerpt: "Unsets specific properties on the group profile." -hidden: false -createdAt: "2020-10-20T00:41:26.260Z" -updatedAt: "2023-09-26T21:06:39.009Z" +title: Delete Property +category: + uri: Ingestion API +content: + excerpt: Unsets specific properties on the group profile. +privacy: + view: public --- + diff --git a/reference/Ingestion API/group-profiles/group-remove-from-list-property.md b/reference/Ingestion API/group-profiles/group-remove-from-list-property.md index 820d13076b..21f295e207 100644 --- a/reference/Ingestion API/group-profiles/group-remove-from-list-property.md +++ b/reference/Ingestion API/group-profiles/group-remove-from-list-property.md @@ -1,8 +1,10 @@ --- -title: "Remove from List Property" -slug: "group-remove-from-list-property" -excerpt: "Removes a specific value in a list property." -hidden: false -createdAt: "2020-10-20T00:41:26.259Z" -updatedAt: "2023-09-26T21:06:39.020Z" +title: Remove from List Property +category: + uri: Ingestion API +content: + excerpt: Removes a specific value in a list property. +privacy: + view: public --- + diff --git a/reference/Ingestion API/group-profiles/group-set-property-once.md b/reference/Ingestion API/group-profiles/group-set-property-once.md index e68eddd00d..18ebea5c12 100644 --- a/reference/Ingestion API/group-profiles/group-set-property-once.md +++ b/reference/Ingestion API/group-profiles/group-set-property-once.md @@ -1,8 +1,12 @@ --- -title: "Set Property Once" -slug: "group-set-property-once" -excerpt: "Adds properties to a group only if the property is not already set. The profile is created if it does not exist." -hidden: false -createdAt: "2020-10-20T00:41:26.258Z" -updatedAt: "2023-09-26T21:06:38.998Z" +title: Set Property Once +category: + uri: Ingestion API +content: + excerpt: >- + Adds properties to a group only if the property is not already set. The + profile is created if it does not exist. +privacy: + view: public --- + diff --git a/reference/Ingestion API/group-profiles/group-set-property.md b/reference/Ingestion API/group-profiles/group-set-property.md index e18f76a777..801a607659 100644 --- a/reference/Ingestion API/group-profiles/group-set-property.md +++ b/reference/Ingestion API/group-profiles/group-set-property.md @@ -1,8 +1,12 @@ --- -title: "Update Property" -slug: "group-set-property" -excerpt: "Updates or adds properties to a group profile. The profile is created if it does not exist." -hidden: false -createdAt: "2020-10-20T00:41:26.256Z" -updatedAt: "2023-09-26T21:06:38.987Z" +title: Update Property +category: + uri: Ingestion API +content: + excerpt: >- + Updates or adds properties to a group profile. The profile is created if it + does not exist. +privacy: + view: public --- + diff --git a/reference/Ingestion API/group-profiles/group-union.md b/reference/Ingestion API/group-profiles/group-union.md index 09c8bb65ab..581c9b24c0 100644 --- a/reference/Ingestion API/group-profiles/group-union.md +++ b/reference/Ingestion API/group-profiles/group-union.md @@ -1,8 +1,13 @@ --- -title: "Union To List Property" -slug: "group-union" -excerpt: "Adds the specified values to a list property on a group profile and ensures that those values only appear once. The profile is created if it does not exist." -hidden: false -createdAt: "2020-10-20T00:41:26.264Z" -updatedAt: "2023-09-26T21:06:39.030Z" +title: Union To List Property +category: + uri: Ingestion API +content: + excerpt: >- + Adds the specified values to a list property on a group profile and ensures + that those values only appear once. The profile is created if it does not + exist. +privacy: + view: public --- + diff --git a/reference/Ingestion API/group-profiles/limits-1.md b/reference/Ingestion API/group-profiles/limits-1.md index 3714f363c1..7c597a9b33 100644 --- a/reference/Ingestion API/group-profiles/limits-1.md +++ b/reference/Ingestion API/group-profiles/limits-1.md @@ -1,8 +1,10 @@ --- -title: "Limits" -slug: "limits-1" -hidden: false -createdAt: "2022-03-31T20:39:06.399Z" -updatedAt: "2022-03-31T20:42:30.062Z" +title: Limits +category: + uri: Ingestion API +content: + excerpt: '' +privacy: + view: public --- The Groups Profile API imposes limits on the total number profile updates that can be sent per request to **2000** as well as limits each individual update in the request to a maximum of **1 MB**. If you are running up against these limits, we suggest breaking your request into smaller batches. Usually, these limits are only hit if you are attempting to do a bulk create/update. diff --git a/reference/Ingestion API/ingestion-api-authentication.md b/reference/Ingestion API/ingestion-api-authentication.md index faa05ecad6..6f80cc66ed 100644 --- a/reference/Ingestion API/ingestion-api-authentication.md +++ b/reference/Ingestion API/ingestion-api-authentication.md @@ -1,8 +1,10 @@ --- -title: "Authentication" -slug: "ingestion-api-authentication" -hidden: false -createdAt: "2021-11-03T20:32:05.864Z" -updatedAt: "2023-06-21T19:29:59.787Z" +title: Authentication +category: + uri: Ingestion API +content: + excerpt: '' +privacy: + view: public --- -Most of our Ingestion API calls such as [Import Events](ref:import-events), [Track Events](ref:track-event), [User Profiles](ref:user-profiles), and [Group Profiles](ref:group-profiles) only require a [Project Token](ref:project-token). Because these APIs are often called from our client-side SDKs, we do not want to expose credentials, but we do need to know which project to send data to so we use the Project Token for that purpose. However, a few of the more powerful APIs such as [Lookup Tables](ref:lookup-tables) **do require authentication**. For these, it's recommended to use a [Service Account](ref:authentication#service-account). We also have legacy support for [Project Secret](ref:project-secret) but suggest any new integrations use a Service Account. \ No newline at end of file +Most of our Ingestion API calls such as [Import Events](ref:import-events), [Track Events](ref:track-event), [User Profiles](ref:user-profiles), and [Group Profiles](ref:group-profiles) only require a [Project Token](ref:project-token). Because these APIs are often called from our client-side SDKs, we do not want to expose credentials, but we do need to know which project to send data to so we use the Project Token for that purpose. However, a few of the more powerful APIs such as [Lookup Tables](ref:lookup-tables) **do require authentication**. For these, it's recommended to use a [Service Account](ref:service-account). We also have legacy support for [Project Secret](ref:project-secret) but suggest any new integrations use a Service Account. diff --git a/reference/Ingestion API/ingestion-api.md b/reference/Ingestion API/ingestion-api.md index ddc5c0f977..ab2eed4d6f 100644 --- a/reference/Ingestion API/ingestion-api.md +++ b/reference/Ingestion API/ingestion-api.md @@ -1,9 +1,11 @@ --- -title: "Overview" -slug: "ingestion-api" -hidden: false -createdAt: "2020-10-20T01:00:32.287Z" -updatedAt: "2023-05-22T22:08:16.158Z" +title: Overview +category: + uri: Ingestion API +content: + excerpt: '' +privacy: + view: public --- Mixpanel's Ingestion APIs allow you to send event or profile data to Mixpanel, which can be analyzed in our reporting interface. @@ -13,8 +15,8 @@ See our [Client-Side vs Server-Side Tracking](https://docs.mixpanel.com/docs/get ## Ingestion HTTP APIs -- [Events](ref:events) -- [Identities](ref:identities) -- [User Profiles](ref:user-profiles) -- [Group Profiles](ref:group-profiles) -- [Lookup Tables](ref:lookup-tables) \ No newline at end of file +* [Events](ref:events) +* [Identities](ref:identities) +* [User Profiles](ref:user-profiles) +* [Group Profiles](ref:group-profiles) +* [Lookup Tables](ref:lookup-tables) diff --git a/reference/Ingestion API/lookup-tables.md b/reference/Ingestion API/lookup-tables.md deleted file mode 100644 index 9e2f70f49e..0000000000 --- a/reference/Ingestion API/lookup-tables.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Lookup Tables" -slug: "lookup-tables" -hidden: false -createdAt: "2020-10-20T00:41:25.537Z" -updatedAt: "2023-09-26T21:06:38.612Z" ---- -Lookup Tables are mutable tables that describe non-user entities like accounts, product SKUs, or geographies. These tables can be used to enrich events at query-time. In star schema terms: events are like facts and Lookup Tables are like dimensions. - -Lookup Tables are [created via the Mixpanel UI](https://help.mixpanel.com/hc/en-us/articles/360044139291-Lookup-tables#stepbystep-guide). This API supports replacing the contents of an existing Lookup Table, which can be used to keep Mixpanel in sync with a source-of-truth system. - -These APIs use [Service Accounts](ref:service-accounts) for authentication. \ No newline at end of file diff --git a/reference/Ingestion API/lookup-tables/_order.yaml b/reference/Ingestion API/lookup-tables/_order.yaml new file mode 100644 index 0000000000..0ac3d26f0f --- /dev/null +++ b/reference/Ingestion API/lookup-tables/_order.yaml @@ -0,0 +1,2 @@ +- list-lookup-tables +- replace-lookup-table diff --git a/reference/Ingestion API/lookup-tables/list-lookup-tables.md b/reference/Ingestion API/lookup-tables/list-lookup-tables.md index 4358713de1..3c2177d824 100644 --- a/reference/Ingestion API/lookup-tables/list-lookup-tables.md +++ b/reference/Ingestion API/lookup-tables/list-lookup-tables.md @@ -1,8 +1,10 @@ --- -title: "List Lookup Tables" -slug: "list-lookup-tables" -excerpt: "Get a list of Lookup Tables defined in the project." -hidden: false -createdAt: "2021-10-05T01:49:31.010Z" -updatedAt: "2023-09-26T21:06:39.072Z" +title: List Lookup Tables +category: + uri: Ingestion API +content: + excerpt: Get a list of Lookup Tables defined in the project. +privacy: + view: public --- + diff --git a/reference/Ingestion API/lookup-tables/replace-lookup-table.md b/reference/Ingestion API/lookup-tables/replace-lookup-table.md index 5f48446f6e..1e139bb15b 100644 --- a/reference/Ingestion API/lookup-tables/replace-lookup-table.md +++ b/reference/Ingestion API/lookup-tables/replace-lookup-table.md @@ -1,10 +1,11 @@ --- -title: "Replace a Lookup Table" -slug: "replace-lookup-table" -excerpt: "" -hidden: false -createdAt: "2021-10-05T01:49:31.011Z" -updatedAt: "2023-09-26T21:06:39.089Z" +title: Replace a Lookup Table +category: + uri: Ingestion API +content: + excerpt: '' +privacy: + view: public --- Lookup Tables must be [created via our UI](https://docs.mixpanel.com/docs/data-structure/lookup-tables#how-do-i-upload-a-lookup-table). Once a Lookup Table is created, its contents can be replaced via this API. @@ -40,12 +41,14 @@ print(resp.json() ``` ### Validation + * The first column of the lookup table is assumed to be the ID of the row. All ID values must be unique. * The first row of the lookup table is a header row. The values in the header must be unique, as each one uniquely identifies a column of the table. These will appear as properties of the lookup table in Mixpanel's UI. * The CSV must be valid according to RFC4180. * If the `Content-Encoding: gzip` header is supplied, the table will be decompressed before parsing. #### Types + * Integers or floats will be parsed as numbers. * RFC3339 timestamps (`2021-08-21T05:36:01Z`) will parsed as datetimes. * `true` or `false` (case-insensitive) will be parsed as boolean. @@ -54,6 +57,7 @@ print(resp.json() * All other values will be treated as strings. #### Errors + Lookup Tables are replaced in their entirety or not replaced at all. When the Lookup Table fails to meet the above validation, we return an error that looks as follows: ```json @@ -76,6 +80,7 @@ Lookup Tables are replaced in their entirety or not replaced at all. When the Lo We will return at most the first 10 rows that failed validation. ### Limits + This endpoint will return a 429 error if called more than 100 times in a rolling 24 hour window. We recommend updating lookup tables at most hourly to stay within this limit. -This endpoint will return a 413 error if a Lookup Table exceeds 100MB uncompressed. In practice, this translates to 1-2M rows. If you have a lookup table that exceeds the limit, we recommend pruning the number of columns to those that are useful to analysis. Removing long URLs or user-generated content can bring a lookup table within this limit. If you still exceed the limit, please reach out to us at apis@mixpanel.com -- we'd love to hear your use case! +This endpoint will return a 413 error if a Lookup Table exceeds 100MB uncompressed. In practice, this translates to 1-2M rows. If you have a lookup table that exceeds the limit, we recommend pruning the number of columns to those that are useful to analysis. Removing long URLs or user-generated content can bring a lookup table within this limit. If you still exceed the limit, please reach out to us at [apis@mixpanel.com](mailto:apis@mixpanel.com) -- we'd love to hear your use case! diff --git a/reference/Ingestion API/user-profiles.md b/reference/Ingestion API/user-profiles.md deleted file mode 100644 index c9a2926f15..0000000000 --- a/reference/Ingestion API/user-profiles.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "User Profiles" -slug: "user-profiles" -hidden: false -createdAt: "2020-10-20T00:41:25.535Z" -updatedAt: "2023-09-26T21:06:38.575Z" ---- diff --git a/reference/Ingestion API/user-profiles/_order.yaml b/reference/Ingestion API/user-profiles/_order.yaml new file mode 100644 index 0000000000..883e81b02f --- /dev/null +++ b/reference/Ingestion API/user-profiles/_order.yaml @@ -0,0 +1,10 @@ +- profile-set +- profile-set-property-once +- profile-numerical-add +- user-profile-union +- profile-append-to-list-property +- profile-remove-from-list-property +- profile-delete-property +- profile-batch-update +- delete-profile +- user-profile-limits diff --git a/reference/Ingestion API/user-profiles/delete-profile.md b/reference/Ingestion API/user-profiles/delete-profile.md index f4e7a99247..fe87320f00 100644 --- a/reference/Ingestion API/user-profiles/delete-profile.md +++ b/reference/Ingestion API/user-profiles/delete-profile.md @@ -1,10 +1,18 @@ --- -title: "Delete Profile" -slug: "delete-profile" -excerpt: "Permanently delete the profile from Mixpanel, along with all of its properties. The $delete object value is ignored - the profile is determined by the $distinct_id from the request itself. +title: Delete Profile +category: + uri: Ingestion API +content: + excerpt: > + Permanently delete the profile from Mixpanel, along with all of its + properties. The $delete object value is ignored - the profile is determined + by the $distinct_id from the request itself. -If you have duplicate profiles, use property $ignore_alias set to true so that you don't delete the original profile when trying to delete the duplicate (as they pass in the alias as the distinct_id)." -hidden: false -createdAt: "2020-10-20T00:41:26.255Z" -updatedAt: "2023-09-26T21:06:38.970Z" + + If you have duplicate profiles, use property $ignore_alias set to true so + that you don't delete the original profile when trying to delete the + duplicate (as they pass in the alias as the distinct_id). +privacy: + view: public --- + diff --git a/reference/Ingestion API/user-profiles/profile-append-to-list-property.md b/reference/Ingestion API/user-profiles/profile-append-to-list-property.md index db67411c24..224db279ec 100644 --- a/reference/Ingestion API/user-profiles/profile-append-to-list-property.md +++ b/reference/Ingestion API/user-profiles/profile-append-to-list-property.md @@ -1,8 +1,14 @@ --- -title: "Append to List Property" -slug: "profile-append-to-list-property" -excerpt: "Takes a JSON object containing keys and values, and appends each to a list associated with the corresponding property name. Appending to a property that doesn't exist will result in assigning a list with one element to that property." -hidden: false -createdAt: "2020-10-20T00:41:26.251Z" -updatedAt: "2023-09-26T21:06:38.789Z" +title: Append to List Property +category: + uri: Ingestion API +content: + excerpt: >- + Takes a JSON object containing keys and values, and appends each to a list + associated with the corresponding property name. Appending to a property + that doesn't exist will result in assigning a list with one element to that + property. +privacy: + view: public --- + diff --git a/reference/Ingestion API/user-profiles/profile-batch-update.md b/reference/Ingestion API/user-profiles/profile-batch-update.md index 0ed39c8a96..33e540664e 100644 --- a/reference/Ingestion API/user-profiles/profile-batch-update.md +++ b/reference/Ingestion API/user-profiles/profile-batch-update.md @@ -1,9 +1,20 @@ --- -title: "Update Multiple Profiles" -slug: "profile-batch-update" -excerpt: "Send a batch of profile updates. Instead of sending a single JSON object as the data query parameter, send a JSON list of objects as the data parameter of an application/json POST or GET request body" -hidden: false -createdAt: "2020-10-20T00:41:26.254Z" -updatedAt: "2023-09-26T21:06:38.914Z" +title: Update Multiple Profiles +category: + uri: Ingestion API +content: + excerpt: >- + Send a batch of profile updates. Instead of sending a single JSON object as + the data query parameter, send a JSON list of objects as the data parameter + of an application/json POST or GET request body. + + + Refer to the respective user profile update commands ($set, $set_once, $add, + $union, $append, $remove, $unset, and $delete) on syntax for their + parameters. +privacy: + view: public --- -[block:callout] { "type": "info", "body": "This API will return a 200 OK even if there are data validation issues. To ensure the request actually succeeded, you need to check the response body." } [/block] +> 📘 +> +> This API will return a 200 OK even if there are data validation issues. To ensure the request actually succeeded, you need to check the response body. diff --git a/reference/Ingestion API/user-profiles/profile-delete-property.md b/reference/Ingestion API/user-profiles/profile-delete-property.md index 51a316487a..cb3a782adf 100644 --- a/reference/Ingestion API/user-profiles/profile-delete-property.md +++ b/reference/Ingestion API/user-profiles/profile-delete-property.md @@ -1,8 +1,12 @@ --- -title: "Delete Property" -slug: "profile-delete-property" -excerpt: "Takes a JSON list of string property names, and permanently removes the properties and their values from a profile." -hidden: false -createdAt: "2020-10-20T00:41:26.253Z" -updatedAt: "2023-09-26T21:06:38.851Z" +title: Delete Property +category: + uri: Ingestion API +content: + excerpt: >- + Takes a JSON list of string property names, and permanently removes the + properties and their values from a profile. +privacy: + view: public --- + diff --git a/reference/Ingestion API/user-profiles/profile-numerical-add.md b/reference/Ingestion API/user-profiles/profile-numerical-add.md index 126d98340a..847505f347 100644 --- a/reference/Ingestion API/user-profiles/profile-numerical-add.md +++ b/reference/Ingestion API/user-profiles/profile-numerical-add.md @@ -1,8 +1,17 @@ --- -title: "Increment Numerical Property" -slug: "profile-numerical-add" -excerpt: 'Takes a JSON object containing keys and numerical values. $add will increment the value of a user profile property. When processed, the property values are added to the existing values of the properties on the profile. If the property is not present on the profile, the value will be added to 0. It is possible to decrement by calling "$add" with negative values. This is useful for maintaining the values of properties like "Number of Logins" or "Files Uploaded".' -hidden: false -createdAt: "2020-10-20T00:41:26.250Z" -updatedAt: "2023-09-26T21:06:38.737Z" +title: Increment Numerical Property +category: + uri: Ingestion API +content: + excerpt: >- + Takes a JSON object containing keys and numerical values. $add will + increment the value of a user profile property. When processed, the property + values are added to the existing values of the properties on the profile. If + the property is not present on the profile, the value will be added to 0. It + is possible to decrement by calling "$add" with negative values. This is + useful for maintaining the values of properties like "Number of Logins" or + "Files Uploaded". +privacy: + view: public --- + diff --git a/reference/Ingestion API/user-profiles/profile-remove-from-list-property.md b/reference/Ingestion API/user-profiles/profile-remove-from-list-property.md index 85364d1533..807a8d3944 100644 --- a/reference/Ingestion API/user-profiles/profile-remove-from-list-property.md +++ b/reference/Ingestion API/user-profiles/profile-remove-from-list-property.md @@ -1,8 +1,13 @@ --- -title: "Remove from List Property" -slug: "profile-remove-from-list-property" -excerpt: "Takes a JSON object containing keys and values. The value in the request is removed from the existing list on the user profile. If it does not exist, no updates are made." -hidden: false -createdAt: "2020-10-20T00:41:26.252Z" -updatedAt: "2023-09-26T21:06:38.815Z" +title: Remove from List Property +category: + uri: Ingestion API +content: + excerpt: >- + Takes a JSON object containing keys and values. The value in the request is + removed from the existing list on the user profile. If it does not exist, no + updates are made. +privacy: + view: public --- + diff --git a/reference/Ingestion API/user-profiles/profile-set-property-once.md b/reference/Ingestion API/user-profiles/profile-set-property-once.md index a7c38056a5..e966f6532b 100644 --- a/reference/Ingestion API/user-profiles/profile-set-property-once.md +++ b/reference/Ingestion API/user-profiles/profile-set-property-once.md @@ -1,8 +1,12 @@ --- -title: "Set Property Once" -slug: "profile-set-property-once" -excerpt: 'Works just like "$set", except it will not overwrite existing property values. This is useful for properties like "First login date".' -hidden: false -createdAt: "2020-10-20T00:41:26.249Z" -updatedAt: "2023-09-26T21:06:38.722Z" +title: Set Property Once +category: + uri: Ingestion API +content: + excerpt: >- + Works just like "$set", except it will not overwrite existing property + values. This is useful for properties like "First login date". +privacy: + view: public --- + diff --git a/reference/Ingestion API/user-profiles/profile-set.md b/reference/Ingestion API/user-profiles/profile-set.md index a81f878e07..746aa9dbbd 100644 --- a/reference/Ingestion API/user-profiles/profile-set.md +++ b/reference/Ingestion API/user-profiles/profile-set.md @@ -1,22 +1,19 @@ --- -title: "Set Property" -slug: "profile-set" -excerpt: "[block:callout]{ \"type\": \"info\", \"body\": \"This API will return a `200 OK` even if there are data validation issues. To ensure the request actually succeeded, you need to check the response body.\"}[/block] [block:callout]{ \"type\": \"info\", \"body\": \"This API does not support gzip encoding.\"}[/block] Takes a JSON object containing names and values of profile properties. If the profile does not exist, it creates it with these properties. If it does exist, it sets the properties to these values, overwriting existing values." -hidden: false -createdAt: "2020-10-20T00:41:26.248Z" -updatedAt: "2023-09-28T17:17:26.122Z" +title: Set Property +category: + uri: Ingestion API +content: + excerpt: >- + Takes a JSON object containing names and values of profile properties. If + the profile does not exist, it creates it with these properties. If it does + exist, it sets the properties to these values, overwriting existing values. +privacy: + view: public --- +
\n\t
\n\n
\n \n You can view and create service accounts in your organization in the Service Accounts tab in your Organization settings\n
\n\n You will be asked to select the role and granted projects of the when creating a service account from the organization's settings page. Deleting a service account from the organization will immediately revoke access to all projects in the organization.\n
\n\n \t![](\"https://files.readme.io/a77f1df-org_settings.png\"/)
\n
\n \n \n
\n\n"
-}
-[/block]
-Any service account you create from the project settings page will be automatically be assigned an admin role. Deleting a service account will revoke access only from that project.
-[block:html]
-{
- "html": "\n \t![](\"https://files.readme.io/37798c5-25f47be-Screen_Shot_2020-07-14_at_4.30.49_PM.png\"/)
\n
\n \n \n
\n\n You can also manage service accounts in your project settings.\n
\n\n ![](\"https://files.readme.io/bcc971b-4f76ee5-Screen_Shot_2020-07-29_at_1.57.16_PM.png\"/)
\n
\n \n"
-}
-[/block]
+> 🚧 Owner or Admin Permissions Required
+>
+> You must have Owner or Admin permissions to manage a project's Service Accounts. Learn more in our [permissions help doc](https://mixpanelsupport.zendesk.com/hc/en-us/articles/360024613412).
+
+\n
+
+
+
+ + You can view and create service accounts in your organization in the Service Accounts tab in your Organization settings +
++ You will be asked to select the role and granted projects of the when creating a service account from the organization's settings page. Deleting a service account from the organization will immediately revoke access to all projects in the organization. +
+
+ 
+
+
+
+
-[block:callout]
-{
- "type": "warning",
- "body": "It's very important you save your service account secret somewhere secure as you won't be able to access it again after creation.",
- "title": "Immediately store your credentials in a safe place"
-}
-[/block]
+
+`}
+ 
+
+
+
+
++ You can also manage service accounts in your project settings. +
+
+ 
+
+
+
+`}
+| + Expression + | + ++ Description + | +
|---|---|
| + `properties["account_id"] in [1,2,3,4]` + | + ++ Returns `true` if `account_id` event property is 1, 2, 3, or 4, otherwise `false`. + | +
| + `user["$email"] == "allison@example.com"` + | + ++ Returns `true` if `$email` user property is "[allison@example.com](mailto:allison@example.com)" otherwise `false`. + | +
| + `defined(properties["My Prop"])` + | + ++ Returns `true` if `My Prop` event property has any value, otherwise `false`. This is the same as "is set" in the UI. + | +
| + `not defined(properties["city"])` + | + ++ Returns `false` if `city` event property has any value, otherwise `true`. This is the same as "is not set" in the UI. + | +
| + + | + ++ + | +
|---|---|
| + **Type** + | + ++ Result + | +
| + **String** + | + ++ Same String + | +
| + **Number** + | + ++ String containing the decimal representation of the number. + | +
| + **Boolean** + | + ++ "true" or "false" + | +
| + **null** + | + ++ null + | +
| + **Undefined** + | + ++ undefined + | +
| + + | + ++ + | +
|---|---|
| + **Type** + | + ++ Result + | +
| + **String** + | + ++ Attempts to interpret the string as a decimal. If this fails, the value becomes undefined. + | +
| + **Number** + | + ++ Same number + | +
| + **Boolean** + | + ++ 1.0 if true, 0.0 if false + | +
| + **null** + | + ++ undefined + | +
| + **undefined** + | + ++ undefined + | +