Skip to main content
POST
/
api
/
app
/
projects
/
{projectId}
/
annotations
Annotations
curl --request POST \
  --url https://mixpanel.com/api/app/projects/{projectId}/annotations \
  --header 'Content-Type: application/json' \
  --data '
{
  "date": "<string>",
  "description": "<string>",
  "tags": [
    {}
  ]
}
'

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mixpanel/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Annotations API

Create and manage annotations to mark important events in your Mixpanel charts.

​
Base URL

https://mixpanel.com/api/app/projects/{projectId}/annotations

​
Authentication

Use Service Account credentials with HTTP Basic Auth.

​
List Annotations

Get all annotations in a project.
​
projectId
number
required
Your Mixpanel project ID
​
fromDate
string
Filter annotations from this date (YYYY-MM-DD HH:mm:ss)
​
toDate
string
Filter annotations to this date (YYYY-MM-DD HH:mm:ss)

​
Example Request

curl "https://mixpanel.com/api/app/projects/123/annotations" \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

​
Create Annotation

Create a new annotation.
​
projectId
number
required
Your Mixpanel project ID
​
date
string
required
Date and time in YYYY-MM-DD HH:mm:ss formatExample: 2024-01-15 12:00:00
​
description
string
required
The text to display for this annotationExample: Product launch - v2.0
​
tags
array
Array of tag IDs to associate with the annotation

​
Example Request

curl "https://mixpanel.com/api/app/projects/123/annotations" \
  -X POST \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-01-15 12:00:00",
    "description": "Launched new homepage design",
    "tags": [1, 2]
  }'

​
Response

{
  "status": "ok",
  "results": {
    "id": 12345,
    "date": "2024-01-15 12:00:00",
    "description": "Launched new homepage design",
    "user": {
      "id": 789,
      "first_name": "John",
      "last_name": "Doe"
    },
    "tags": [
      {"id": 1, "name": "Product"},
      {"id": 2, "name": "Launch"}
    ]
  }
}

​
Get Annotation

Retrieve details of a specific annotation.
​
projectId
number
required
Your Mixpanel project ID
​
annotationId
number
required
The ID of the annotation

​
Example Request

curl "https://mixpanel.com/api/app/projects/123/annotations/12345" \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

​
Update Annotation

Update an existing annotation.
​
projectId
number
required
Your Mixpanel project ID
​
annotationId
number
required
The ID of the annotation to update
​
description
string
Updated description text
​
tags
array
Updated array of tag IDs

​
Example Request

curl "https://mixpanel.com/api/app/projects/123/annotations/12345" \
  -X PATCH \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated: Launched new homepage with A/B test",
    "tags": [1, 2, 3]
  }'

​
Delete Annotation

Permanently delete an annotation.
​
projectId
number
required
Your Mixpanel project ID
​
annotationId
number
required
The ID of the annotation to delete

​
Example Request

curl "https://mixpanel.com/api/app/projects/123/annotations/12345" \
  -X DELETE \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

​
Manage Annotation Tags

​
List All Tags

curl "https://mixpanel.com/api/app/projects/123/annotations/tags" \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

​
Create Tag

curl "https://mixpanel.com/api/app/projects/123/annotations/tags" \
  -X POST \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing Campaign"}'

​
Best Practices

Include context about what happened:
{
    "description": "Product Launch: v2.0 - New checkout flow",
    "date": "2024-01-15 14:00:00"
}
Create tags for different categories:
  • Product launches
  • Marketing campaigns
  • Bug fixes
  • Infrastructure changes
Create annotations programmatically during deployments:
import requests
import os

def create_deployment_annotation(version):
    requests.post(
        f'https://mixpanel.com/api/app/projects/{os.getenv("PROJECT_ID")}/annotations',
        auth=(os.getenv("MP_USERNAME"), os.getenv("MP_SECRET")),
        json={
            'date': datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
            'description': f'Deployed version {version}'
        }
    )