Endpoints

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

Endpoints

PATCH
DELETE
GET
POST
GET
POST
GET
GET
POST
GET
POST
GET
← Previous page

Update endpoints

Update an existing endpoint.

Required API key scopes

endpoint:write

Path parameters

  • name
    string

Request parameters

  • name
    stringnull
  • query
  • description
    stringnull
  • data_freshness_seconds
    integernull
  • is_active
    booleannull
  • is_materialized
    booleannull
  • derived_from_insight
    stringnull
  • version
    integernull
  • bucket_overrides
    objectnull
  • deleted
    booleannull
  • tags
    arraynull
  • optional_breakdown_properties
    arraynull

Response


Example request

PATCH /api/projects/:project_id/endpoints/:name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/:name/\
	-d name=["string","null"]

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "query": null,
  "is_active": true,
  "data_freshness_seconds": 0,
  "endpoint_path": "string",
  "url": "string",
  "ui_url": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "is_materialized": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "versions_count": 0,
  "derived_from_insight": "string",
  "last_executed_at": "2019-08-24T14:15:22Z",
  "materialization": {
    "name": "string",
    "status": "string",
    "can_materialize": true,
    "reason": "string",
    "last_materialized_at": "string",
    "error": "string",
    "saved_query_id": "841a020c-dad2-4bac-a071-aaf3f5af0641"
  },
  "bucket_overrides": {},
  "columns": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "tags": [
    "string"
  ],
  "optional_breakdown_properties": [
    "string"
  ]
}

Delete endpoints

Delete an endpoint and clean up materialized query.

Required API key scopes

endpoint:write

Path parameters

  • name
    string

Example request

DELETE /api/projects/:project_id/endpoints/:name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/:name/

Example response

Status 204 No response body

Retrieve endpoints logs

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Query parameters

  • after
    string
  • before
    string
  • instance_id
    string
  • level
    string
  • limit
    integer
    Default: 50
  • search
    string

Example request

GET /api/projects/:project_id/endpoints/:name/logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/:name/logs/

Example response

Status 200 No response body

Create endpoints materialization preview

Preview the materialization transform for an endpoint. Shows what the query will look like after materialization, including range pair detection and bucket functions.

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Request parameters

  • version
    integer
  • bucket_overrides
    objectnull

Example request

POST /api/projects/:project_id/endpoints/:name/materialization_preview
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/endpoints/:name/materialization_preview/\
	-d version="integer"

Example response

Status 200 No response body

Retrieve endpoints materialization status

Get materialization status for an endpoint. Supports ?version=N query param.

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Response


Example request

GET /api/projects/:project_id/endpoints/:name/materialization_status
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/:name/materialization_status/

Example response

Status 200
RESPONSE
{
  "name": "string",
  "status": "string",
  "can_materialize": true,
  "reason": "string",
  "last_materialized_at": "string",
  "error": "string",
  "saved_query_id": "841a020c-dad2-4bac-a071-aaf3f5af0641"
}

Create endpoints materialization suggestion

Ask AI to rewrite the endpoint's query into a semantically equivalent form that can be materialized. Only applicable to SQL (HogQL) endpoints that currently fail the materialization checks. The suggestion is validated against the live checks before being returned; nothing is saved. Requires the organization's AI data processing approval.

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Request parameters

  • version
    integernull

Response


Example request

POST /api/projects/:project_id/endpoints/:name/materialization_suggestion
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/endpoints/:name/materialization_suggestion/\
	-d version=["integer","null"]

Example response

Status 200
RESPONSE
{
  "suggestion_status": "ok",
  "suggested_query": "string",
  "explanation": "string",
  "attempts": 0,
  "error": "string",
  "original_reason": "string"
}

Retrieve endpoints openapi spec

Get OpenAPI 3.0 specification for this endpoint. Use this to generate typed SDK clients.

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Query parameters

  • version
    integer

Example request

GET /api/projects/:project_id/endpoints/:name/openapi.json
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/:name/openapi.json/

Example response

Status 200 No response body

Retrieve endpoints run

Execute endpoint with optional materialization. Supports version parameter, runs latest version if not set.

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Response


Example request

GET /api/projects/:project_id/endpoints/:name/run
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/:name/run/

Example response

Status 200
RESPONSE
{
  "name": "string",
  "execution_id": "02ca5b65-a269-4c45-8d4a-0c74ff3ae670",
  "results": [
    null
  ],
  "columns": [
    "string"
  ],
  "hasMore": true,
  "endpoint_version": 0
}

Create endpoints run

Execute endpoint with optional materialization. Supports version parameter, runs latest version if not set.

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Request parameters

  • client_query_id
  • debug
    Default: false
  • filters_override
  • limit
  • offset
  • refresh
    Default: cache
  • variables
  • version

Response


Example request

POST /api/projects/:project_id/endpoints/:name/run
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/endpoints/:name/run/\
	-d client_query_id=undefined

Example response

Status 200
RESPONSE
{
  "name": "string",
  "execution_id": "02ca5b65-a269-4c45-8d4a-0c74ff3ae670",
  "results": [
    null
  ],
  "columns": [
    "string"
  ],
  "hasMore": true,
  "endpoint_version": 0
}

List all endpoints versions

List all versions for an endpoint.

Required API key scopes

endpoint:read

Path parameters

  • name
    string

Query parameters

  • created_by
    integer
  • is_active
    boolean
  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/endpoints/:name/versions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/:name/versions/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "query": null,
      "is_active": true,
      "data_freshness_seconds": 0,
      "endpoint_path": "string",
      "url": "string",
      "ui_url": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "is_materialized": true,
      "current_version": 0,
      "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
      "versions_count": 0,
      "derived_from_insight": "string",
      "last_executed_at": "2019-08-24T14:15:22Z",
      "materialization": {
        "name": "string",
        "status": "string",
        "can_materialize": true,
        "reason": "string",
        "last_materialized_at": "string",
        "error": "string",
        "saved_query_id": "841a020c-dad2-4bac-a071-aaf3f5af0641"
      },
      "bucket_overrides": {},
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "tags": [
        "string"
      ],
      "optional_breakdown_properties": [
        "string"
      ],
      "version": 0,
      "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
      "endpoint_is_active": true,
      "version_created_at": "string",
      "version_updated_at": "string",
      "version_created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      }
    }
  ]
}

Create endpoints last execution times

Get the most recent execution time per endpoint (endpoint-level). Timestamps are recorded by the run path for personal-API-key calls. For per-version usage, query the query_log table directly.

Required API key scopes

endpoint:read

Request parameters

  • names
    array

Response


Example request

POST /api/projects/:project_id/endpoints/last_execution_times
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/endpoints/last_execution_times/\
	-d names="array"

Example response

Status 200
RESPONSE
{
  "query_status": {
    "complete": false,
    "dashboard_id": null,
    "end_time": null,
    "error": false,
    "error_code": null,
    "error_message": null,
    "expiration_time": null,
    "id": "string",
    "insight_id": null,
    "labels": null,
    "pickup_time": null,
    "query_async": true,
    "query_progress": null,
    "results": null,
    "start_time": null,
    "task_id": null,
    "team_id": 0
  }
}

Retrieve endpoints materialization conditions

Get the source code of the live materialization checks, plus the rewrite contract. Lets an agent rewrite a rejected endpoint query itself: fetch these conditions, produce a semantically equivalent query that passes every check, update the endpoint with it, then confirm via materialization_status. The source is read from the running system, so it always matches the checks this instance enforces.

Required API key scopes

endpoint:read

Response


Example request

GET /api/projects/:project_id/endpoints/materialization_conditions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/endpoints/materialization_conditions/

Example response

Status 200
RESPONSE
{
  "conditions_source": "string",
  "rewrite_contract": "string"
}
← Previous page

Community questions

Questions about this page? or post a community question.