Metrics

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`GET`
`POST`
`GET`
`POST`
`GET`
`POST`
`GET`
`GET`
`GET`
`GET`
`POST`

Retrieve metrics attribute values

Observed values for one metric attribute key, most frequent first. Backs the filter bar's value autocomplete. metricName limits choices to one metric.

Required API key scopes

metrics:read

Query parameters

dateFrom
string | null
dateTo
string | null
key
string
limit
integer
Default: 100
metricName
string
Default:
value
string
Default:

Response

Example request

GET /api/projects/:project_id/metrics/attribute_values
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/attribute_values/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/attribute_values/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "count": 0
    }
  ]
}

Retrieve metrics attribute values

Observed values for one metric attribute key, most frequent first. Backs the filter bar's value autocomplete. metricName limits choices to one metric.

Required API key scopes

metrics:read

Query parameters

dateFrom
string | null
dateTo
string | null
key
string
limit
integer
Default: 100
metricName
string
Default:
value
string
Default:

Response

Example request

GET /api/projects/:project_id/metrics/attribute_values
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/attribute_values/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/attribute_values/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "count": 0
    }
  ]
}

Retrieve metrics attributes

Attribute keys ordered by distinct series count, from highest to lowest. metricName limits choices to one metric.

Required API key scopes

metrics:read

Query parameters

dateFrom
string | null
dateTo
string | null
limit
integer
Default: 100
metricName
string
Default:
search
string
Default:

Response

Example request

GET /api/projects/:project_id/metrics/attributes
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/attributes/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/attributes/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "name": "string",
      "value_count": 0
    }
  ],
  "count": 0
}

Retrieve metrics attributes

Attribute keys ordered by distinct series count, from highest to lowest. metricName limits choices to one metric.

Required API key scopes

metrics:read

Query parameters

dateFrom
string | null
dateTo
string | null
limit
integer
Default: 100
metricName
string
Default:
search
string
Default:

Response

Example request

GET /api/projects/:project_id/metrics/attributes
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/attributes/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/attributes/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "name": "string",
      "value_count": 0
    }
  ],
  "count": 0
}

Create metrics characterize

Characterize a metric anomaly: compare an anomaly window against a baseline, find the onset, and rank which label values moved.

Required API key scopes

metrics:read

Request parameters

query

Response

Example request

POST /api/projects/:project_id/metrics/characterize
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/characterize/\
	-d query=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/metrics/characterize/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "metric_name": "string",
  "aggregation": "string",
  "interval": "string",
  "baseline_from": "string",
  "baseline_to": "string",
  "anomaly_from": "string",
  "anomaly_to": "string",
  "baseline_mean": 0.1,
  "baseline_stddev": 0.1,
  "anomaly_mean": 0.1,
  "anomaly_peak": 0.1,
  "change_ratio": 0.1,
  "direction": "up",
  "onset_time": "string",
  "top_movers": [
    {
      "key": "string",
      "label": "string",
      "baseline_value": 0.1,
      "anomaly_value": 0.1,
      "change_ratio": 0.1
    }
  ],
  "series": {
    "labels": {
      "property1": "string",
      "property2": "string"
    },
    "points": [
      {
        "time": "string",
        "value": 0
      }
    ],
    "metric_name": "string",
    "clause": "string",
    "unit": "string"
  }
}

Create metrics characterize

Characterize a metric anomaly: compare an anomaly window against a baseline, find the onset, and rank which label values moved.

Required API key scopes

metrics:read

Request parameters

query

Response

Example request

POST /api/projects/:project_id/metrics/characterize
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/characterize/\
	-d query=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/metrics/characterize/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "metric_name": "string",
  "aggregation": "string",
  "interval": "string",
  "baseline_from": "string",
  "baseline_to": "string",
  "anomaly_from": "string",
  "anomaly_to": "string",
  "baseline_mean": 0.1,
  "baseline_stddev": 0.1,
  "anomaly_mean": 0.1,
  "anomaly_peak": 0.1,
  "change_ratio": 0.1,
  "direction": "up",
  "onset_time": "string",
  "top_movers": [
    {
      "key": "string",
      "label": "string",
      "baseline_value": 0.1,
      "anomaly_value": 0.1,
      "change_ratio": 0.1
    }
  ],
  "series": {
    "labels": {
      "property1": "string",
      "property2": "string"
    },
    "points": [
      {
        "time": "string",
        "value": 0
      }
    ],
    "metric_name": "string",
    "clause": "string",
    "unit": "string"
  }
}

List all metrics dashboard imports

The user's dashboard imports of the last 7 days that used the agent, with the progress of the ones that run.

Required API key scopes

metrics:read

Example request

GET /api/projects/:project_id/metrics/dashboard_imports
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/dashboard_imports/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/dashboard_imports/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "string",
  "source": "grafana",
  "status": "running",
  "dashboard_name": "string",
  "phase": "starting",
  "panel_progress": [
    {
      "key": "string",
      "title": "string",
      "state": "waiting"
    }
  ],
  "layout_rounds": 0,
  "layout_round": 0,
  "dashboard_id": 0,
  "error": "string",
  "summary": {
    "total": 0,
    "imported": 0,
    "approximated": 0,
    "failed": 0,
    "skipped": 0
  },
  "panels": [
    {
      "key": "string",
      "title": "string",
      "outcome": "imported",
      "reason": "string"
    }
  ]
}

Create metrics dashboard imports

Import a Grafana dashboard JSON model or a dashboard screenshot as a new dashboard. Panels that match the project's metrics import at once. An AI agent converts the rest, and the response then has an id to poll.

Required API key scopes

metrics:readdashboard:writeinsight:write

Request parameters

source
name
string
grafana_json
string
image_base64
string

Response

Example request

POST /api/projects/:project_id/metrics/dashboard_imports
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/dashboard_imports/\
	-d source=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/metrics/dashboard_imports/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 201

RESPONSE
{
  "id": "string",
  "source": "grafana",
  "status": "running",
  "dashboard_name": "string",
  "phase": "starting",
  "panel_progress": [
    {
      "key": "string",
      "title": "string",
      "state": "waiting"
    }
  ],
  "layout_rounds": 0,
  "layout_round": 0,
  "dashboard_id": 0,
  "error": "string",
  "summary": {
    "total": 0,
    "imported": 0,
    "approximated": 0,
    "failed": 0,
    "skipped": 0
  },
  "panels": [
    {
      "key": "string",
      "title": "string",
      "outcome": "imported",
      "reason": "string"
    }
  ]
}

Status 403 AI data processing is off, the AI credits ran out, or no access.

Status 409 The user already has 3 imports that are running.

Retrieve metrics dashboard imports

Status of one of the user's dashboard imports. Poll it until the status is not 'running'.

Required API key scopes

metrics:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/metrics/dashboard_imports/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/dashboard_imports/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/dashboard_imports/{metric_id}/".format(
        project_id=project_id,
		metric_id="<the metric id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "string",
  "source": "grafana",
  "status": "running",
  "dashboard_name": "string",
  "phase": "starting",
  "panel_progress": [
    {
      "key": "string",
      "title": "string",
      "state": "waiting"
    }
  ],
  "layout_rounds": 0,
  "layout_round": 0,
  "dashboard_id": 0,
  "error": "string",
  "summary": {
    "total": 0,
    "imported": 0,
    "approximated": 0,
    "failed": 0,
    "skipped": 0
  },
  "panels": [
    {
      "key": "string",
      "title": "string",
      "outcome": "imported",
      "reason": "string"
    }
  ]
}

Create metrics dashboard imports validate

Check dashboard panel queries before they go on a dashboard: the metrics must exist, PromQL must run, and SQL must compile and read only logs or traces.

Required API key scopes

metrics:read

Request parameters

panels
array
import_id
string | null

Response

Example request

POST /api/projects/:project_id/metrics/dashboard_imports/validate
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/dashboard_imports/validate/\
	-d panels="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/metrics/dashboard_imports/validate/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"panels": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "key": "string",
      "valid": true,
      "error": "string",
      "notes": [
        "string"
      ]
    }
  ]
}

Retrieve metrics error spikes

Error Tracking issue spikes detected in a time window — backs the metrics chart's error-spike overlay (PoC). Team-wide: not yet scoped to the metric's own service.

Required API key scopes

metrics:readerror_tracking:read

Query parameters

dateFrom
string
dateTo
string

Response

Example request

GET /api/projects/:project_id/metrics/error_spikes
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/error_spikes/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/error_spikes/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "detected_at": "string",
      "issue_id": "string",
      "issue_name": "string"
    }
  ]
}

Retrieve metrics error spikes

Error Tracking issue spikes detected in a time window — backs the metrics chart's error-spike overlay (PoC). Team-wide: not yet scoped to the metric's own service.

Required API key scopes

metrics:readerror_tracking:read

Query parameters

dateFrom
string
dateTo
string

Response

Example request

GET /api/projects/:project_id/metrics/error_spikes
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/error_spikes/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/error_spikes/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "detected_at": "string",
      "issue_id": "string",
      "issue_name": "string"
    }
  ]
}

Retrieve metrics has metrics

Required API key scopes

metrics:read

Response

Example request

GET /api/projects/:project_id/metrics/has_metrics
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/has_metrics/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/has_metrics/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "hasMetrics": true
}

Retrieve metrics has metrics

Required API key scopes

metrics:read

Response

Example request

GET /api/projects/:project_id/metrics/has_metrics
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/has_metrics/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/has_metrics/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "hasMetrics": true
}

Retrieve metrics names

Distinct metric names for the viewer picker, without sparklines or caching.

Required API key scopes

metrics:read

Query parameters

limit
integer
Default: 100
service
string
value
string
Default:

Response

Example request

GET /api/projects/:project_id/metrics/names
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/names/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/names/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "name": "string",
      "metric_type": "string"
    }
  ]
}

Retrieve metrics names

Distinct metric names for the viewer picker, without sparklines or caching.

Required API key scopes

metrics:read

Query parameters

limit
integer
Default: 100
service
string
value
string
Default:

Response

Example request

GET /api/projects/:project_id/metrics/names
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/names/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/names/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "name": "string",
      "metric_type": "string"
    }
  ]
}

Retrieve metrics overview

Ingestion rollup for the overview page: freshness of the newest datapoint plus per-service metric/series counts over the last day.

Required API key scopes

metrics:read

Response

Example request

GET /api/projects/:project_id/metrics/overview
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/overview/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/overview/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "last_seen": "string",
  "metric_names": 0,
  "series": 0,
  "lookback_seconds": 0,
  "services": [
    {
      "service_name": "string",
      "metric_names": 0,
      "series": 0,
      "last_seen": "string"
    }
  ]
}

Retrieve metrics overview

Ingestion rollup for the overview page: freshness of the newest datapoint plus per-service metric/series counts over the last day.

Required API key scopes

metrics:read

Response

Example request

GET /api/projects/:project_id/metrics/overview
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/overview/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/metrics/overview/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "last_seen": "string",
  "metric_names": 0,
  "series": 0,
  "lookback_seconds": 0,
  "services": [
    {
      "service_name": "string",
      "metric_names": 0,
      "series": 0,
      "last_seen": "string"
    }
  ]
}

Create metrics query

Required API key scopes

metrics:read

Request parameters

query

Response

Example request

POST /api/projects/:project_id/metrics/query
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/query/\
	-d query=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/metrics/query/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "labels": {
        "property1": "string",
        "property2": "string"
      },
      "points": [
        {
          "time": "string",
          "value": 0
        }
      ],
      "metric_name": "string",
      "clause": "string",
      "unit": "string"
    }
  ],
  "hint": "string"
}

Create metrics query

Required API key scopes

metrics:read

Request parameters

query

Response

Example request

POST /api/projects/:project_id/metrics/query
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/metrics/query/\
	-d query=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/metrics/query/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "labels": {
        "property1": "string",
        "property2": "string"
      },
      "points": [
        {
          "time": "string",
          "value": 0
        }
      ],
      "metric_name": "string",
      "clause": "string",
      "unit": "string"
    }
  ],
  "hint": "string"
}