> ## 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.

# Insights

> Query saved Insights reports

# Query Insights

Retrieve data from your saved Insights reports programmatically.

## Query Saved Report

<ParamField query="project_id" type="integer" required>
  Your Mixpanel project ID
</ParamField>

<ParamField query="workspace_id" type="integer">
  The workspace ID containing the report
</ParamField>

<ParamField query="bookmark_id" type="integer" required>
  The ID of your Insights report. Can be found from the URL:
  `https://mixpanel.com/project/<PROJECT_ID>/view/<WORKSPACE_ID>/app/boards#id=12345&editor-card-id="report-<BOOKMARK_ID>"`
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://mixpanel.com/api/query/insights?project_id=123&bookmark_id=456" \
    -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET
  ```

  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  response = requests.get(
      'https://mixpanel.com/api/query/insights',
      auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET'),
      params={
          'project_id': 123,
          'bookmark_id': 456
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript theme={null}
  const username = 'SERVICE_ACCOUNT_USERNAME';
  const password = 'SERVICE_ACCOUNT_SECRET';
  const auth = 'Basic ' + btoa(username + ':' + password);

  fetch('https://mixpanel.com/api/query/insights?project_id=123&bookmark_id=456', {
    headers: {
      'Authorization': auth
    }
  })
  .then(response => response.json())
  .then(data => console.log(data));
  ```
</CodeGroup>

### Response

<ResponseField name="computed_at" type="string">
  Timestamp when the query was computed
</ResponseField>

<ResponseField name="date_range" type="object">
  The date range of the queried data

  <Expandable title="date_range">
    <ResponseField name="from_date" type="string">
      Start date of the range
    </ResponseField>

    <ResponseField name="to_date" type="string">
      End date of the range
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="headers" type="array">
  Array explaining the nested keys in the `series` object
</ResponseField>

<ResponseField name="series" type="object">
  Maps event names to date/value pairs. Each key is an event name, and the value is an object with dates as keys and event counts as values.
</ResponseField>

<CodeGroup>
  ```json 200 Success theme={null}
  {
    "computed_at": "2020-09-21T16:35:41.252314+00:00",
    "date_range": {
      "from_date": "2020-08-31T00:00:00-07:00",
      "to_date": "2020-09-12T23:59:59.999000-07:00"
    },
    "headers": ["$event"],
    "series": {
      "Logged in": {
        "2020-08-31T00:00:00-07:00": 9852,
        "2020-09-07T00:00:00-07:00": 4325
      },
      "Viewed page": {
        "2020-08-31T00:00:00-07:00": 10246,
        "2020-09-07T00:00:00-07:00": 11432
      }
    }
  }
  ```
</CodeGroup>

## Use Cases

### Daily Metrics Dashboard

<CodeGroup>
  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth
  from datetime import datetime

  def get_daily_metrics(project_id, bookmark_id):
      """Fetch daily event metrics from Insights"""
      
      response = requests.get(
          'https://mixpanel.com/api/query/insights',
          auth=HTTPBasicAuth('USERNAME', 'SECRET'),
          params={
              'project_id': project_id,
              'bookmark_id': bookmark_id
          }
      )
      
      data = response.json()
      
      # Process the series data
      metrics = {}
      for event_name, date_values in data['series'].items():
          total = sum(date_values.values())
          metrics[event_name] = {
              'total': total,
              'daily_breakdown': date_values
          }
      
      return metrics

  # Usage
  metrics = get_daily_metrics(123, 456)
  print(f"Total Signups: {metrics['Signed Up']['total']}")
  ```
</CodeGroup>

### Trend Analysis

<CodeGroup>
  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  def analyze_trend(project_id, bookmark_id):
      """Calculate growth trends from Insights data"""
      
      response = requests.get(
          'https://mixpanel.com/api/query/insights',
          auth=HTTPBasicAuth('USERNAME', 'SECRET'),
          params={'project_id': project_id, 'bookmark_id': bookmark_id}
      )
      
      data = response.json()
      
      for event_name, date_values in data['series'].items():
          dates = sorted(date_values.keys())
          values = [date_values[d] for d in dates]
          
          if len(values) >= 2:
              # Calculate week-over-week growth
              current_week = sum(values[-7:])
              previous_week = sum(values[-14:-7])
              growth = ((current_week - previous_week) / previous_week) * 100
              
              print(f"{event_name}: {growth:.1f}% WoW growth")

  analyze_trend(123, 456)
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Create dedicated reports for API queries">
    Instead of querying general reports, create specific Insights reports optimized for API consumption with:

    * Relevant date ranges
    * Specific events needed
    * Appropriate filters
  </Accordion>

  <Accordion title="Cache results appropriately">
    Insights data doesn't change frequently, so cache results:

    ```python theme={null}
    import time
    import json

    def get_cached_insights(project_id, bookmark_id, cache_duration=3600):
        cache_file = f'insights_{project_id}_{bookmark_id}.json'
        
        # Check if cache exists and is fresh
        try:
            with open(cache_file, 'r') as f:
                cache = json.load(f)
                if time.time() - cache['timestamp'] < cache_duration:
                    return cache['data']
        except FileNotFoundError:
            pass
        
        # Fetch fresh data
        data = fetch_insights(project_id, bookmark_id)
        
        # Save to cache
        with open(cache_file, 'w') as f:
            json.dump({
                'timestamp': time.time(),
                'data': data
            }, f)
        
        return data
    ```
  </Accordion>

  <Accordion title="Handle missing data gracefully">
    Some dates might not have data:

    ```python theme={null}
    series = data['series'].get('Event Name', {})
    value = series.get('2024-01-15', 0)  # Default to 0 if missing
    ```
  </Accordion>
</AccordionGroup>