Data

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

Endpoints

GET
GET
GET
GET
GET
GET
PATCH
DELETE
POST
GET
POST
DELETE
POST
GET
GET
GET
GET
GET
GET
GET

Retrieve data warehouse check database name

Check if a database name is available.

Query parameters

  • name
    string

Response


Example request

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

Example response

Status 200
RESPONSE
{
"name": "string",
"available": true
}

Retrieve data warehouse check schema name

Check if a schema name is free within the organization's managed warehouse.

Query parameters

  • name
    string

Response


Example request

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

Example response

Status 200
RESPONSE
{
"name": "string",
"available": true
}

Retrieve data warehouse completed activity

Returns completed/non-running activities (jobs with status 'Completed'). Supports pagination and cutoff time filtering.

Query parameters

  • cutoff_days
    integer
    Default: 30
  • kind
    string
    Default: all
    One of: "all""import""model"
  • limit
    integer
    Default: 20
  • offset
    integer
    Default: 0
  • outcome
    string
    Default: completed
    One of: "completed""failed""all"

Response


Example request

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

Example response

Status 200
RESPONSE
{
"results": [
{
"id": "string",
"type": "string",
"name": "string",
"status": "string",
"rows": 0,
"created_at": "2019-08-24T14:15:22Z",
"finished_at": "2019-08-24T14:15:22Z",
"latest_error": "string",
"workflow_run_id": "string",
"origin": "string",
"source_id": "string"
}
],
"next": "string",
"previous": "string"
}
Status 500 The activity query failed.
RESPONSE
{
"error": "string"
}

Retrieve data warehouse data health issues

Returns failed/disabled data pipeline items for the Pipeline status side panel. Includes: materializations, syncs, sources, destinations, and transformations.

Required API key scopes

warehouse_view:readexternal_data_source:readbatch_export:readhog_function:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
"results": [
{
"id": "string",
"name": "string",
"type": "string",
"source_type": "string",
"sync_type": "string",
"status": "string",
"error": "string",
"failed_at": "2019-08-24T14:15:22Z",
"url": "string"
}
],
"count": 0
}
Status 500 The health query failed.
RESPONSE
{
"error": "string"
}

Retrieve data warehouse data ops dashboard

Returns the data ops overview dashboard ID for this team, creating it if it doesn't exist yet.

Required API key scopes

warehouse_view:write

Example request

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

Example response

Status 200 No response body

Retrieve data warehouse data quality gate

Read or update the team's data quality gate: whether a materialization whose error-severity checks fail is published.

Required API key scopes

warehouse_view:write

Response


Example request

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

Example response

Status 200
RESPONSE
{
"gate_materialization_on_checks": true
}

Update data warehouse data quality gate

Read or update the team's data quality gate: whether a materialization whose error-severity checks fail is published.

Required API key scopes

warehouse_view:write

Request parameters

  • gate_materialization_on_checks
    boolean

Response


Example request

PATCH /api/projects/:project_id/data_warehouse/data_quality_gate
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/data_warehouse/data_quality_gate/\
-d gate_materialization_on_checks="boolean"

Example response

Status 200
RESPONSE
{
"gate_materialization_on_checks": true
}

Delete data warehouse delete org

Remove the organization's provisioning record after teardown, freeing its warehouse name.

Called once the warehouse status reports deleted: deprovision tears the warehouse down, this removes the now-empty org row so the database_name can be reused. Restricted to organization admins.

Required API key scopes

warehouse_view:write

Response


Example request

DELETE /api/projects/:project_id/data_warehouse/delete-org
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/data_warehouse/delete-org/

Example response

Status 200
RESPONSE
{
"status": "string",
"org": "string"
}

Create data warehouse deprovision

Start deprovisioning the organization's managed warehouse. Restricted to organization admins.

Required API key scopes

warehouse_view:write

Response


Example request

POST /api/projects/:project_id/data_warehouse/deprovision
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/data_warehouse/deprovision/

Example response

Status 202
RESPONSE
{
"status": "string",
"org": "string"
}

Retrieve data warehouse hoglake credentials

The organization's live hoglake OAuth credentials (never their secrets), and where to use them.

Required API key scopes

warehouse_view:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
"hoglake_credentials": [
{
"client_id": "string",
"name": "string",
"scope": "string",
"kind": "string",
"owner_user_uuid": "8e6b26d6-d7de-41d0-abd4-63d489fecb81",
"owner_email": "string",
"owner_name": "string",
"team_ids": [
0
],
"created_at": "2019-08-24T14:15:22Z",
"last_rotated_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z",
"revoked_at": "2019-08-24T14:15:22Z"
}
],
"connect": {
"catalog": "string",
"hoglake_url": "string",
"token_url": "string"
}
}

Create data warehouse hoglake credentials

Create an OAuth client credential for the managed hoglake catalog. The secret is in this response only.

Required API key scopes

warehouse_view:write

Request parameters

  • name
    string
  • scope
  • ttl_seconds
    integer

Response


Example request

POST /api/projects/:project_id/data_warehouse/hoglake_credentials
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/data_warehouse/hoglake_credentials/\
-d name="string",\
-d scope=undefined

Example response

Status 201
RESPONSE
{
"client_id": "string",
"client_secret": "string",
"name": "string",
"scope": "string",
"expires_at": "2019-08-24T14:15:22Z",
"kind": "string"
}

Delete data warehouse hoglake credentials

Revoke the credential now: new tokens are refused and its S3 vends stop.

Required API key scopes

warehouse_view:write

Path parameters

  • credential_id
    string

Response


Example request

DELETE /api/projects/:project_id/data_warehouse/hoglake_credentials/:credential_id
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/data_warehouse/hoglake_credentials/:credential_id/

Example response

Status 200
RESPONSE
{
"revoked": "string"
}

Create data warehouse hoglake credentials rotate

Replace the credential's secret; the old one stops working. The new secret is in this response only.

Required API key scopes

warehouse_view:write

Path parameters

  • credential_id
    string

Response


Example request

POST /api/projects/:project_id/data_warehouse/hoglake_credentials/:credential_id/rotate
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/data_warehouse/hoglake_credentials/:credential_id/rotate/

Example response

Status 200
RESPONSE
{
"client_id": "string",
"client_secret": "string",
"name": "string",
"scope": "string",
"expires_at": "2019-08-24T14:15:22Z",
"kind": "string"
}

Retrieve data warehouse job stats

Returns success and failed job statistics for the last 1, 7, or 30 days. Query parameter 'days' can be 1, 7, or 30 (default: 7).

Query parameters

  • days
    integer
    Default: 7
    One of: "1""7""30"

Response


Example request

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

Example response

Status 200
RESPONSE
{
"days": 0,
"cutoff_time": "2019-08-24T14:15:22Z",
"total_jobs": 0,
"successful_jobs": 0,
"failed_jobs": 0,
"external_data_jobs": {
"total": 0,
"running": 0,
"successful": 0,
"failed": 0
},
"modeling_jobs": {
"total": 0,
"running": 0,
"successful": 0,
"failed": 0
},
"breakdown": {
"property1": {
"successful": 0,
"failed": 0
},
"property2": {
"successful": 0,
"failed": 0
}
}
}
Status 400 `days` was not 1, 7 or 30.
RESPONSE
{
"error": "string"
}
Status 500 The statistics query failed.
RESPONSE
{
"error": "string"
}

Retrieve data warehouse managed warehouse data status

Get events, persons, and imported source readiness for the managed warehouse.

Required API key scopes

warehouse_view:readexternal_data_source:read

Response


Example request

GET /api/projects/:project_id/data_warehouse/managed-warehouse-data-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/data_warehouse/managed-warehouse-data-status/

Example response

Status 200
RESPONSE
{
"overall_readiness_state": "not_configured",
"events": {
"dataset": "events",
"readiness_state": "not_configured",
"detail": "string",
"completed_partitions": 0,
"total_partitions": 0,
"current_partition": "string",
"last_updated_at": "2019-08-24T14:15:22Z"
},
"persons": {
"dataset": "events",
"readiness_state": "not_configured",
"detail": "string",
"completed_partitions": 0,
"total_partitions": 0,
"current_partition": "string",
"last_updated_at": "2019-08-24T14:15:22Z"
},
"sources": {
"readiness_state": "not_configured",
"detail": "string",
"sources": [
{
"source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
"source_name": "string",
"source_type": "string",
"readiness_state": "not_configured",
"detail": "string",
"total_schemas": 0,
"applied_schemas": 0,
"last_applied_at": "2019-08-24T14:15:22Z",
"last_synced_at": "2019-08-24T14:15:22Z"
}
]
},
"generated_at": "2019-08-24T14:15:22Z"
}

Retrieve data warehouse managed warehouse monitoring

Get tenant-safe live worker, session, queue, and capacity data for the current organization.

Required API key scopes

warehouse_view:read

Response


Example request

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

Example response

Status 200 Current organization-scoped worker and query activity.
RESPONSE
{
"schema_version": 1,
"org_id": "string",
"as_of": "2019-08-24T14:15:22Z",
"warehouse": {
"state": "string"
},
"limits": {
"max_workers": 0,
"max_vcpus": 0,
"default_worker_cpu": "string",
"default_worker_memory": "string",
"default_worker_ttl_seconds": 0,
"default_worker_min_hot_idle": 0
},
"totals": {
"workers": 0,
"allocated_cpu_cores": 0.1,
"allocated_memory_bytes": 0,
"active_sessions": 0,
"running_queries": 0,
"queued_connections": 0
},
"workers": [
{
"id": "string",
"state": "string",
"cpu": "string",
"memory": "string",
"ttl_seconds": 0,
"created_at": "2019-08-24T14:15:22Z",
"last_heartbeat_at": "2019-08-24T14:15:22Z",
"session": {
"protocol": "string",
"state": "string",
"elapsed_ms": 0,
"percentage": 0,
"rows": 0,
"total_rows": 0,
"stalled": true
}
}
],
"coverage": {
"cp_responders": 0,
"cp_total": 0,
"partial": true
}
}
Status 400 The monitoring query parameters are invalid.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 403 Managed warehouse monitoring is not available to the caller.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 404 The organization does not have a managed warehouse, or this endpoint does not match its query engine.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 501 Managed warehouse monitoring is not configured.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 502 The managed warehouse monitoring service returned an invalid response or was unreachable.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 504 The managed warehouse monitoring service timed out.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}

Retrieve data warehouse managed warehouse monitoring timeseries

Get one allow-listed monitoring metric for the current organization and trailing time window.

Required API key scopes

warehouse_view:read

Query parameters

  • metric
    string
    One of: "query_rate""error_ratio""duration_p50""duration_p95""sessions_active""acquire_p95""acquire_by_source""storage_bytes""worker_crash_rate"
  • window
    string
    Default: 24h
    One of: "1h""6h""24h""7d""30d"

Response


Example request

GET /api/projects/:project_id/data_warehouse/managed-warehouse-monitoring-timeseries
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/data_warehouse/managed-warehouse-monitoring-timeseries/

Example response

Status 200 One organization-scoped monitoring metric over time.
RESPONSE
{
"schema_version": 1,
"org_id": "string",
"metric": "string",
"unit": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"step_seconds": 1,
"series": [
{
"labels": {
"property1": "string",
"property2": "string"
},
"points": [
{
"timestamp": "2019-08-24T14:15:22Z",
"value": 0.1
}
]
}
]
}
Status 400 The monitoring query parameters are invalid.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 403 Managed warehouse monitoring is not available to the caller.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 404 The organization does not have a managed warehouse, or this endpoint does not match its query engine.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 501 Managed warehouse monitoring is not configured.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 502 The managed warehouse monitoring service returned an invalid response or was unreachable.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 504 The managed warehouse monitoring service timed out.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}

Retrieve data warehouse managed warehouse source schemas

Per-schema backfill and live import status for one source, for the Overview tab's drill-down modal — the main status endpoint only returns a per-source rollup.

Required API key scopes

warehouse_view:readexternal_data_source:read

Query parameters

  • source_id
    string

Response


Example request

GET /api/projects/:project_id/data_warehouse/managed-warehouse-source-schemas
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/data_warehouse/managed-warehouse-source-schemas/

Example response

Status 200
RESPONSE
{
"schemas": [
{
"schema_id": "9c37f32d-8308-4815-9b0d-83fa3c1b25f9",
"source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
"source_name": "string",
"source_type": "string",
"table_name": "string",
"readiness_state": "not_configured",
"detail": "string",
"workflow_type": "copy",
"workflow_status": "running",
"workflow_started_at": "2019-08-24T14:15:22Z",
"applied": true,
"last_applied_at": "2019-08-24T14:15:22Z",
"last_synced_at": "2019-08-24T14:15:22Z"
}
]
}

Retrieve data warehouse managed warehouse trino monitoring

Get tenant-safe live Trino query totals, limits, and in-flight queries for the current organization.

Required API key scopes

warehouse_view:read

Response


Example request

GET /api/projects/:project_id/data_warehouse/managed-warehouse-trino-monitoring
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/data_warehouse/managed-warehouse-trino-monitoring/

Example response

Status 200 Current organization-scoped Trino query activity.
RESPONSE
{
"schema_version": 1,
"org_id": "string",
"as_of": "2019-08-24T14:15:22Z",
"trino": {
"state": "string",
"ready_at": "2019-08-24T14:15:22Z",
"failed_at": "2019-08-24T14:15:22Z"
},
"available": true,
"limits": {
"max_running_queries": 0,
"max_queued_queries": 0
},
"totals": {
"in_flight": 0,
"running": 0,
"queued": 0,
"blocked": 0,
"longest_running_ms": 0,
"physical_input_bytes": 0
},
"queries": [
{
"query_id": "string",
"state": "string",
"user": "string",
"source": "string",
"query": "string",
"created_at": "2019-08-24T14:15:22Z",
"elapsed_ms": 0,
"queued_ms": 0,
"cpu_ms": 0,
"physical_input_bytes": 0,
"peak_memory_bytes": 0,
"processed_input_rows": 0,
"progress_percentage": 0,
"blocked": true
}
],
"queries_truncated": true
}
Status 400 The monitoring query parameters are invalid.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 403 Managed warehouse monitoring is not available to the caller.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 404 The organization does not have a managed warehouse, or this endpoint does not match its query engine.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 501 Managed warehouse monitoring is not configured.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 502 The managed warehouse monitoring service returned an invalid response or was unreachable.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 504 The managed warehouse monitoring service timed out.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}

Retrieve data warehouse managed warehouse trino monitoring timeseries

Get one allow-listed Trino monitoring metric for the current organization and trailing time window.

Required API key scopes

warehouse_view:read

Query parameters

  • metric
    string
    One of: "queries_in_flight""query_rate""error_ratio""duration_p50""duration_p95""queue_time_p95""scanned_bytes_rate""cpu_seconds_rate""storage_bytes"
  • window
    string
    Default: 24h
    One of: "1h""6h""24h""7d""30d"

Response


Example request

GET /api/projects/:project_id/data_warehouse/managed-warehouse-trino-monitoring-timeseries
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/data_warehouse/managed-warehouse-trino-monitoring-timeseries/

Example response

Status 200 One organization-scoped Trino monitoring metric over time.
RESPONSE
{
"schema_version": 1,
"org_id": "string",
"metric": "string",
"unit": "string",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"step_seconds": 1,
"series": [
{
"labels": {
"property1": "string",
"property2": "string"
},
"points": [
{
"timestamp": "2019-08-24T14:15:22Z",
"value": 0.1
}
]
}
]
}
Status 400 The monitoring query parameters are invalid.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 403 Managed warehouse monitoring is not available to the caller.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 404 The organization does not have a managed warehouse, or this endpoint does not match its query engine.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 501 Managed warehouse monitoring is not configured.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 502 The managed warehouse monitoring service returned an invalid response or was unreachable.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}
Status 504 The managed warehouse monitoring service timed out.
RESPONSE
{
"error": "string",
"type": "string",
"code": "string",
"detail": "string",
"attr": "string"
}