endpoints

Create a new endpoint.

post/api/projects/{project_id}/endpoints/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/endpoints/
  • 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

namestring nullable

Unique URL-safe name. Must start with a letter, only letters/numbers/hyphens/underscores, max 128 chars.

queryunknown
descriptionstring nullable

Human-readable description of what this endpoint returns.

data_freshness_secondsinteger nullable

How fresh the data should be, in seconds. Must be one of: 900 (15 min), 1800 (30 min), 3600 (1 h), 21600 (6 h), 43200 (12 h), 86400 (24 h, default), 604800 (7 d). Controls cache TTL and materialization sync frequency.

is_activeboolean nullable

Whether this endpoint is available for execution via the API.

is_materializedboolean nullable

Whether query results are materialized to S3.

derived_from_insightstring nullable

Short ID of the insight this endpoint was derived from.

versioninteger nullable

Target a specific version for updates (defaults to current version).

bucket_overridesobject nullable

Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys.

deletedboolean nullable

Set to true to soft-delete this endpoint.

tagsstring[] nullable

List of tag names to associate with this endpoint. Replaces any existing tags.

optional_breakdown_propertiesstring[] nullable

Breakdown property names that may be omitted on /run. Omitted ones return data aggregated across all values of that breakdown. Defaults to [] — every breakdown variable is required.

Response

idstring uuid required

Unique endpoint identifier (UUID).

namestring required

URL-safe endpoint name, unique per team.

descriptionstring nullable required

Human-readable description of the endpoint.

queryunknown required
is_activeboolean required

Whether the endpoint can be executed via the API.

data_freshness_secondsinteger required

How fresh the data is, in seconds. One of: 900, 1800, 3600, 21600, 43200, 86400, 604800.

endpoint_pathstring required

Relative API path to execute this endpoint (e.g. /api/projects/{team_id}/endpoints/{name}/run).

urlstring nullable required

Absolute URL to execute this endpoint.

ui_urlstring nullable required

Absolute URL to view this endpoint in the PostHog UI.

created_atstring date-time required

When the endpoint was created (ISO 8601).

updated_atstring date-time required

When the endpoint was last updated (ISO 8601).

is_materializedboolean required

Whether the current version's results are pre-computed to S3.

current_versioninteger required

Latest version number.

current_version_idstring uuid nullable

UUID of the current EndpointVersion row.

versions_countinteger required

Total number of versions for this endpoint.

derived_from_insightstring nullable required

Short ID of the source insight, if derived from one.

last_executed_atstring date-time nullable required

When this endpoint was last executed via the API (ISO 8601), or null if never executed.

bucket_overridesobject nullable required

Per-column bucket overrides for range variable materialization.

tagsstring[] required

Tag names associated with this endpoint.

optional_breakdown_propertiesstring[] required

Breakdown property names that may be omitted on /run. Omitted ones return data aggregated across all values of that breakdown.

Changes

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