data_catalog

Create a metric, or refine the one already holding this name for the team.

post/api/projects/{project_id}/data_catalog/metrics/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/data_catalog/metrics/
  • Auth: HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

idstring uuid required
namestring required

Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving.

display_namestring

Human-friendly label. Mutable, unlike name.

descriptionstring required

What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put rationale for query choices in 'reasoning'.

unitstring

Unit of the result, e.g. usd, percent, cents.

ownerstring nullable required

Email of the human accountable for this metric, or null.

definitionobject nullable

Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.

definition_kindstring nullable required

Query kind of the definition (HogQLQuery, TrendsQuery, ...), or null for a stub.

referenced_table_namesunknown required
statusstring required

Persisted lifecycle state: 'proposed' or 'approved'. Drift is reported separately.

is_driftedboolean required

True when the definition has drifted from its linked source insight (or the insight is gone).

approved_atstring date-time nullable required
source_insight_short_idstring nullable

Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition.

last_run_atstring date-time nullable required

When the metric was last run (30-minute throttle).

created_source'user' | 'ai_generated'
  • user - user
  • ai_generated - ai_generated
ai_modelstring

Model that generated the metric, if AI-authored.

confidencenumber double nullable

AI author's confidence in the proposal, 0-1.

reasoningstring

AI author's reasoning, surfaced as review context.

created_atstring date-time required
updated_atstring date-time nullable required

Response

idstring uuid required
namestring required

Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving.

display_namestring

Human-friendly label. Mutable, unlike name.

descriptionstring required

What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put rationale for query choices in 'reasoning'.

unitstring

Unit of the result, e.g. usd, percent, cents.

ownerstring nullable required

Email of the human accountable for this metric, or null.

definitionobject nullable

Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.

definition_kindstring nullable required

Query kind of the definition (HogQLQuery, TrendsQuery, ...), or null for a stub.

referenced_table_namesunknown required
statusstring required

Persisted lifecycle state: 'proposed' or 'approved'. Drift is reported separately.

is_driftedboolean required

True when the definition has drifted from its linked source insight (or the insight is gone).

approved_atstring date-time nullable required
source_insight_short_idstring nullable

Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition.

last_run_atstring date-time nullable required

When the metric was last run (30-minute throttle).

created_source'user' | 'ai_generated'
  • user - user
  • ai_generated - ai_generated
ai_modelstring

Model that generated the metric, if AI-authored.

confidencenumber double nullable

AI author's confidence in the proposal, 0-1.

reasoningstring

AI author's reasoning, surfaced as review context.

created_atstring date-time required
updated_atstring date-time nullable required

Changes

No recorded changes to this operation across all 1 revision of this API.