Mixpanel

Send events to Mixpanel, keep user profiles current, export raw event data, and annotate the charts.

Actions

Action	What it does
Append to profile list	Add values to list properties on a person's Mixpanel profile, keeping duplicates.
Create annotation	Mark a moment on the project's charts with a note - a release, a campaign, an outage - so anyone reading a report later can see what caused the change.
Create annotation tag	Create a tag that annotations can be filed under, such as Releases or Outages, so they can be filtered on a chart.
Delete annotation	Remove a Mixpanel annotation for good.
Delete profile	Permanently delete a person's Mixpanel profile and all of its properties.
Delete profile properties	Permanently remove named properties, and their values, from a person's Mixpanel profile.
Export raw events	Download events exactly as Mixpanel stored them, with every property, over a date range.
Find profiles	Read user profiles out of Mixpanel, filtered by an expression or by a list of ids.
Get annotation	Read one Mixpanel annotation by its id, with its date, note, tags and who created it.
Import events	Load a batch of events into Mixpanel, including ones that already happened.
Increment profile properties	Add to numeric properties on a person's Mixpanel profile - a login count, a lifetime spend.
List annotation tags	List the tags this project's annotations can be filed under, with the numeric ids the other annotation actions want.
List annotations	List the project's chart annotations, optionally only those inside a date range.
Merge into profile list	Add values to list properties on a person's Mixpanel profile, skipping any the list already holds.
Remove from profile list	Take values out of list properties on a person's Mixpanel profile.
Send event	Record one event in Mixpanel for a person, with any properties you want attached.
Set profile properties	Set properties on a person's Mixpanel profile, replacing whatever was there.
Set profile properties once	Set properties on a person's Mixpanel profile only where nothing is set yet, leaving existing values alone.
Update annotation	Change a Mixpanel annotation's note or its tags.
Update many profiles	Apply a list of profile changes in one call, each naming its own person and operation.

Append to profile list

Add values to list properties on a person's Mixpanel profile, keeping duplicates. Use Merge into profile list instead when the list is a set and a repeat should be ignored.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
Values to appendpropertiesobjectRequired: Property names and the value to append to each.

Outputs

distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "operation": "$append",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Create annotation

Mark a moment on the project's charts with a note - a release, a campaign, an outage - so anyone reading a report later can see what caused the change.

Inputs

Whenannotation_datedate and timeRequired: The moment on the chart this note marks.
NotedescriptiontextRequired: The text shown when someone hovers the marker.
Tagstag_idslist: Tags to file this annotation under. Pick from the project's tags, or type an id - a tag created by an earlier step in this workflow is usable before the list has been refreshed.

Outputs

annotationobject
annotation_idnumber: The new annotation's id
statustext: Status of the action execution ("success" on success).

Example output

{
  "annotation": {
    "date": "2026-09-01 09:00:00",
    "description": "Pricing page redesign shipped to 100% of traffic",
    "id": 4821,
    "tags": [
      {
        "id": 12,
        "name": "Releases"
      }
    ],
    "user": {
      "first_name": "Alex",
      "id": 771,
      "last_name": "Rivera"
    }
  },
  "annotation_id": 4821,
  "status": "success"
}

Create annotation tag

Create a tag that annotations can be filed under, such as Releases or Outages, so they can be filtered on a chart.

Inputs

Tag namenametextRequired: The label shown on annotations carrying this tag.

Outputs

statustext: Status of the action execution ("success" on success).
tagobject
tag_idnumber: The new tag's id

Example output

{
  "status": "success",
  "tag": {
    "has_annotations": true,
    "id": 12,
    "name": "Releases",
    "project_id": 3018488
  },
  "tag_id": 12
}

Delete annotation

Remove a Mixpanel annotation for good. Takes the annotation's numeric id.

Inputs

Annotationannotation_idnumberRequired: The annotation's numeric id. Use List annotations to find one.

Outputs

annotation_idnumber: The annotation that was deleted
deletedtrue/false: True once it is gone
statustext: Status of the action execution ("success" on success).

Example output

{
  "annotation_id": 4821,
  "deleted": true,
  "status": "success"
}

Delete profile

Permanently delete a person's Mixpanel profile and all of its properties. Their events stay in the project - only Mixpanel's own privacy tools remove those.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
Do not follow aliasesignore_aliastrue/false: Turn this on when deleting a duplicate profile. Without it Mixpanel follows the alias and deletes the original instead.Default: false.

Outputs

deletedtrue/false: True once it is gone
distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "deleted": true,
  "distinct_id": "user-4821",
  "operation": "$delete",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Delete profile properties

Permanently remove named properties, and their values, from a person's Mixpanel profile. The profile itself stays.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
Properties to removeproperty_nameslistRequired: Names of the properties to remove. Up to 255 in one call.

Outputs

distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
properties_removedlist: The property names that were removed
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "operation": "$unset",
  "properties_removed": [
    "Trial Ends"
  ],
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Export raw events

Download events exactly as Mixpanel stored them, with every property, over a date range. Available on every Mixpanel plan.

Inputs

Fromfrom_datedate: First day to include. Leave both dates empty to read the last 7 days.
Toto_datedate: Last day to include. Leave both dates empty to read the last 7 days.
Only these eventsevent_nameslist: Names of the events to include. Leave empty for all of them.
Filter expressionwheretext: A Mixpanel expression, such as properties["Plan"] == "premium". Leave empty for everything. The grammar is at https://docs.mixpanel.com/reference/segmentation-expressions
How many eventslimitnumber: The most events to return. Defaults to 100. A workflow step holds the whole result in memory, so keep this modest.From 1 to 10000. Default: 100.

Outputs

countnumber: How many events came back
eventslist
from_datetext: First day read
statustext: Status of the action execution ("success" on success).
to_datetext: Last day read

Example output

{
  "count": 1,
  "events": [
    {
      "event": "Invoice Paid",
      "properties": {
        "$insert_id": "b3f1c2d4-5e6a-47b8-9c0d-1e2f3a4b5c6d",
        "Amount": 49,
        "distinct_id": "user-4821",
        "time": 1788000000
      }
    }
  ],
  "from_date": "2026-09-01",
  "status": "success",
  "to_date": "2026-09-07"
}

Find profiles

Read user profiles out of Mixpanel, filtered by an expression or by a list of ids. Available on every Mixpanel plan.

Inputs

Filter expressionwheretext: A Mixpanel expression, such as properties["Plan"] == "premium". Leave empty for everything. The grammar is at https://docs.mixpanel.com/reference/segmentation-expressions
Only these peopledistinct_idslist: Distinct IDs to look up. Leave empty to use the filter expression instead.
Only these propertiesoutput_propertieslist: Property names to return. Naming the few you need makes the query markedly faster on a large project. Leave empty for all of them.
Only this cohortfilter_by_cohort_idnumber: The numeric id of a saved cohort to draw from. Saving cohorts needs a paid Mixpanel plan, so leave this empty on a free project.
Include people with no profileinclude_all_userstrue/false: Only applies when a cohort is given. On by default, which includes everyone in the cohort even if they have no profile.Default: true.
Pagepagenumber: Which page to read, counting from 0. Anything above 0 also needs the session id from the first page.From 0 to 10000.
Session IDsession_idtext: The session id returned by the first page, which is what lets Mixpanel page through the same result instead of running the search again.

Outputs

countnumber: How many profiles are on this page
pagenumber: The page number returned
page_sizenumber: The most profiles Mixpanel puts on one page
profileslist
session_idtext: Pass this back to read the next page
statustext: Status of the action execution ("success" on success).
totalnumber: How many profiles match in total

Example output

{
  "count": 1,
  "page": 0,
  "page_size": 1000,
  "profiles": [
    {
      "$distinct_id": "user-4821",
      "$properties": {
        "$email": "alex@example.com",
        "$name": "Alex Rivera",
        "Plan": "premium"
      }
    }
  ],
  "session_id": "1788000000-EXAMPL",
  "status": "success",
  "total": 1
}

Get annotation

Read one Mixpanel annotation by its id, with its date, note, tags and who created it.

Inputs

Annotationannotation_idnumberRequired: The annotation's numeric id. Use List annotations to find one.

Outputs

annotationobject
annotation_idnumber: The annotation's id
statustext: Status of the action execution ("success" on success).

Example output

{
  "annotation": {
    "date": "2026-09-01 09:00:00",
    "description": "Pricing page redesign shipped to 100% of traffic",
    "id": 4821,
    "tags": [
      {
        "id": 12,
        "name": "Releases"
      }
    ],
    "user": {
      "first_name": "Alex",
      "id": 771,
      "last_name": "Rivera"
    }
  },
  "annotation_id": 4821,
  "status": "success"
}

Load a batch of events into Mixpanel, including ones that already happened. Use this for backfills and for anything older than the last hour, which Send event will not take. Needs the service account to be an Owner or an Admin.

Inputs

EventseventslistRequired: The events to load. Each needs a name and one of distinct_id, user_id or device_id; a time and a deduplication id are filled in when you leave them out. Up to 2000 per call.

Outputs

events_importednumber: How many Mixpanel reported it stored
events_submittednumber: How many events this call sent
insert_idslist: The deduplication id of each event, generated where one was not supplied - resend these to retry safely.
statustext: Status of the action execution ("success" on success).

Example output

{
  "events_imported": 2,
  "events_submitted": 2,
  "insert_ids": [
    "b3f1c2d4-5e6a-47b8-9c0d-1e2f3a4b5c6d",
    "c4a2d3e5-6f7b-48c9-8d1e-2f3a4b5c6d7e"
  ],
  "status": "success"
}

Increment profile properties

Add to numeric properties on a person's Mixpanel profile - a login count, a lifetime spend. A negative amount subtracts, and a property that does not exist yet counts up from zero.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
Amounts to addpropertiesobjectRequired: Property names and the number to add to each.

Outputs

distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "operation": "$add",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

List annotation tags

List the tags this project's annotations can be filed under, with the numeric ids the other annotation actions want.

Inputs

None.

Outputs

countnumber: How many came back
statustext: Status of the action execution ("success" on success).
tagslist

Example output

{
  "count": 1,
  "status": "success",
  "tags": [
    {
      "has_annotations": true,
      "id": 12,
      "name": "Releases",
      "project_id": 3018488
    }
  ]
}

List annotations

List the project's chart annotations, optionally only those inside a date range.

Inputs

Fromfrom_datedate: First day to include. Leave both dates empty for every annotation in the project.
Toto_datedate: Last day to include. Leave both dates empty for every annotation in the project.

Outputs

annotationslist
countnumber: How many came back
statustext: Status of the action execution ("success" on success).

Example output

{
  "annotations": [
    {
      "date": "2026-09-01 09:00:00",
      "description": "Pricing page redesign shipped to 100% of traffic",
      "id": 4821,
      "tags": [
        {
          "id": 12,
          "name": "Releases"
        }
      ],
      "user": {
        "first_name": "Alex",
        "id": 771,
        "last_name": "Rivera"
      }
    }
  ],
  "count": 1,
  "status": "success"
}

Merge into profile list

Add values to list properties on a person's Mixpanel profile, skipping any the list already holds. This is the one to use for tags, plans and features, where a value should appear once.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
Values to merge inpropertiesobjectRequired: Property names and a list of values for each. Each value must be a list, even for a single entry.

Outputs

distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "operation": "$union",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Remove from profile list

Take values out of list properties on a person's Mixpanel profile.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
Values to removepropertiesobjectRequired: Property names and the value to remove from each.

Outputs

distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "operation": "$remove",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Send event

Record one event in Mixpanel for a person, with any properties you want attached. Use this to get whatever a workflow does into your product analytics as it happens.

Inputs

Event nameeventtextRequired: What happened, as you want it to appear in Mixpanel - for example 'Invoice Paid'. A new name creates a new event.
Distinct IDdistinct_idtext: Mixpanel's identifier for this person. Leave empty to let Mixpanel derive it from the User ID or Device ID. Give at least one of Distinct ID, User ID or Device ID. Mixpanel cannot attribute an event that has none of them.
User IDuser_idtext: Your own id for this person once they are known - their id in your database. Mixpanel stores it as $user_id and makes it the canonical Distinct ID. Give at least one of Distinct ID, User ID or Device ID. Mixpanel cannot attribute an event that has none of them.
Device IDdevice_idtext: The anonymous id this person browsed under before they were known. Sending it alongside a User ID is what stitches their pre-login and post-login activity into one person. Give at least one of Distinct ID, User ID or Device ID. Mixpanel cannot attribute an event that has none of them.
Event propertiespropertiesobject: Details of this occurrence, as name/value pairs.
When it happenedtimedate and time: Leave empty for now. Mixpanel keeps events roughly in the present here - use Import events for anything older.
Deduplication IDinsert_idtext: An id unique to this occurrence, so a workflow that runs twice records the event once. Letters, digits and hyphens, up to 36 characters.
IP addressiptext: The person's IP address, if you have it, so Mixpanel can fill in their city and country. Leave empty to record no location - the alternative would be this server's.

Outputs

distinct_idtext: Who Mixpanel attributed the event to
eventtext: The event name recorded
insert_idtext: The deduplication id sent, if any
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "event": "Invoice Paid",
  "insert_id": "b3f1c2d4-5e6a-47b8-9c0d-1e2f3a4b5c6d",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Set profile properties

Set properties on a person's Mixpanel profile, replacing whatever was there. Creates the profile if it does not exist. Mixpanel's own names start with a dollar sign - $email, $name, $phone.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
PropertiespropertiesobjectRequired: The properties to set, as name/value pairs.
Update the profile's location from this requestupdate_geolocationtrue/false: Off by default, and usually right to leave off: the request comes from a Lodol server, so turning this on stamps a data centre's city onto the profile instead of the person's.Default: false.

Outputs

distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "operation": "$set",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Set profile properties once

Set properties on a person's Mixpanel profile only where nothing is set yet, leaving existing values alone. Use it for things that should record the first time they happened, such as a signup date or first referrer.

Inputs

Distinct IDdistinct_idtextRequired: Whose profile to change. This is the person's canonical Distinct ID - the same value as their User ID on a project using Simplified ID Merge.
PropertiespropertiesobjectRequired: The properties to set if they are not set already.
Update the profile's location from this requestupdate_geolocationtrue/false: Off by default, and usually right to leave off: the request comes from a Lodol server, so turning this on stamps a data centre's city onto the profile instead of the person's.Default: false.

Outputs

distinct_idtext: Whose profile was changed
operationtext: The Mixpanel operation used, such as $set
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_id": "user-4821",
  "operation": "$set_once",
  "records_accepted": 1,
  "status": "success",
  "verbose": true
}

Update annotation

Change a Mixpanel annotation's note or its tags. Its date cannot be moved through the API - delete it and create another to change when it marks.

Inputs

Annotationannotation_idnumberRequired: The annotation's numeric id. Use List annotations to find one.
Notedescriptiontext: New text for the annotation. Leave empty to keep it.
Tagstag_idslist: Tags to file this annotation under. Pick from the project's tags, or type an id - a tag created by an earlier step in this workflow is usable before the list has been refreshed.

Outputs

annotationobject
annotation_idnumber: The annotation's id
statustext: Status of the action execution ("success" on success).

Example output

{
  "annotation": {
    "date": "2026-09-01 09:00:00",
    "description": "Pricing page redesign shipped to 100% of traffic",
    "id": 4821,
    "tags": [
      {
        "id": 12,
        "name": "Releases"
      }
    ],
    "user": {
      "first_name": "Alex",
      "id": 771,
      "last_name": "Rivera"
    }
  },
  "annotation_id": 4821,
  "status": "success"
}

Update many profiles

Apply a list of profile changes in one call, each naming its own person and operation. Use this instead of a loop when a workflow has a list of people to update.

Inputs

UpdatesupdateslistRequired: One entry per change. Each needs a $distinct_id and exactly one operation: $set, $set_once, $add, $union, $append, $remove, $unset or $delete. Up to 2000 per call.

Outputs

distinct_idslist: The profiles that were changed
records_acceptednumber: How many records this call sent and Mixpanel accepted
statustext: Status of the action execution ("success" on success).
verbosetrue/false: True when Mixpanel confirmed the write in detail. False means it answered the short form, which does not distinguish a good project token from a bad one.

Example output

{
  "distinct_ids": [
    "user-4821",
    "user-4822"
  ],
  "records_accepted": 2,
  "status": "success",
  "verbose": true
}

ActionsCopy Anchor Link

Append to profile listCopy Anchor Link

Inputs

Outputs

Create annotationCopy Anchor Link

Inputs

Outputs

Create annotation tagCopy Anchor Link

Inputs

Outputs

Delete annotationCopy Anchor Link

Inputs

Outputs

Delete profileCopy Anchor Link

Inputs

Outputs

Delete profile propertiesCopy Anchor Link

Inputs

Outputs

Export raw eventsCopy Anchor Link

Inputs

Outputs

Find profilesCopy Anchor Link

Inputs

Outputs

Get annotationCopy Anchor Link

Inputs

Outputs

Import eventsCopy Anchor Link

Inputs

Outputs

Increment profile propertiesCopy Anchor Link

Inputs

Outputs

List annotation tagsCopy Anchor Link

Inputs

Outputs

List annotationsCopy Anchor Link

Inputs

Outputs

Merge into profile listCopy Anchor Link

Inputs

Outputs

Remove from profile listCopy Anchor Link

Inputs

Outputs

Send eventCopy Anchor Link

Inputs

Outputs

Set profile propertiesCopy Anchor Link

Inputs

Outputs

Set profile properties onceCopy Anchor Link

Inputs

Outputs

Update annotationCopy Anchor Link

Inputs

Outputs

Update many profilesCopy Anchor Link

Inputs

Outputs

On this page

Actions

Append to profile list

Create annotation

Create annotation tag

Delete annotation

Delete profile

Delete profile properties

Export raw events

Find profiles

Get annotation

Import events

Increment profile properties

List annotation tags

List annotations

Merge into profile list

Remove from profile list

Send event

Set profile properties

Set profile properties once

Update annotation

Update many profiles