Data API Reference

Data

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

Endpoints

`GET`
`GET`
`GET`
`GET`
`DELETE`
`POST`
`POST`
`GET`
`GET`
`GET`
`GET`
`POST`
`POST`
`GET`
`GET`
`GET`
`GET`
`GET`
`GET`
`GET`

Retrieve environments data warehouse check database name

Check if a database name is available.

Query parameters

name
string

Response

Example request

GET /api/environments/:environment_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/environments/:environment_id/data_warehouse/check-database-name/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/check-database-name/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

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

Retrieve environments data warehouse completed activity

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

Example request

GET /api/environments/:environment_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/environments/:environment_id/data_warehouse/completed_activity/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/completed_activity/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments 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:read

Example request

GET /api/environments/:environment_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/environments/:environment_id/data_warehouse/data_health_issues/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/data_health_issues/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments 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/environments/:environment_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/environments/:environment_id/data_warehouse/data_ops_dashboard/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/data_ops_dashboard/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Delete environments 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/environments/:environment_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/environments/:environment_id/data_warehouse/delete-org/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/delete-org/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 200

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

Create environments 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/environments/:environment_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/environments/:environment_id/data_warehouse/deprovision/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/deprovision/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 202

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

Create environments data warehouse enable backfill

Enable warehouse backfill for this environment with a dedicated set of tables.

Requires a table name and records the environment's membership in the organization's managed warehouse. Restricted to organization admins.

Required API key scopes

warehouse_view:write

Request parameters

table_name
string

Response

Example request

POST /api/environments/:environment_id/data_warehouse/enable_backfill
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/environments/:environment_id/data_warehouse/enable_backfill/\
	-d table_name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/enable_backfill/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"table_name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "enabled": true,
  "table_suffix": "string"
}

Retrieve environments 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).

Example request

GET /api/environments/:environment_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/environments/:environment_id/data_warehouse/job_stats/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/job_stats/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments 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/environments/:environment_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/environments/:environment_id/data_warehouse/managed-warehouse-data-status/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/managed-warehouse-data-status/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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,
        "backfilled_schemas": 0,
        "pending_batches": 0,
        "last_synced_at": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "generated_at": "2019-08-24T14:15:22Z"
}

Retrieve environments 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/environments/:environment_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/environments/:environment_id/data_warehouse/managed-warehouse-source-schemas/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/managed-warehouse-source-schemas/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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",
      "backfilled": true,
      "completed_chunks": 0,
      "total_chunks": 0,
      "pending_batches": 0,
      "oldest_pending_at": "2019-08-24T14:15:22Z",
      "last_applied_at": "2019-08-24T14:15:22Z",
      "last_synced_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve environments data warehouse property values

API endpoints for data warehouse aggregate statistics and operations.

Required API key scopes

query:read

Example request

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

Example response

Status 200 No response body

Create environments data warehouse provision

Start provisioning a managed warehouse for this organization (shared by all its teams).

Required API key scopes

warehouse_view:write

Request parameters

database_name
string
table_name
string

Response

Example request

POST /api/environments/:environment_id/data_warehouse/provision
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/environments/:environment_id/data_warehouse/provision/\
	-d database_name="string",\
	-d table_name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/provision/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"database_name": "string",
		"table_name": "string"
	}
).json()

Example response

Status 202

RESPONSE
{
  "status": "string",
  "org": "string",
  "username": "string",
  "password": "string"
}

Create environments data warehouse reset password

Reset the root password for the managed warehouse.

Required API key scopes

warehouse_view:write

Response

Example request

POST /api/environments/:environment_id/data_warehouse/reset-password
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/environments/:environment_id/data_warehouse/reset-password/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/data_warehouse/reset-password/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "username": "string",
  "password": "string"
}

Retrieve environments data warehouse running activity

Returns currently running activities (jobs with status 'Running'). Supports pagination and cutoff time filtering.

Example request

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

Example response

Status 200 No response body

Retrieve environments data warehouse total rows stats

Returns aggregated statistics for the data warehouse total rows processed within the current billing period. Used by the frontend data warehouse scene to display usage information.

Example request

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

Example response

Status 200 No response body

Retrieve environments data warehouse warehouse status

Get the current provisioning status of the managed warehouse, with this project's backfill state.

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "org_id": "string",
  "state": "pending",
  "status_message": "string",
  "s3_state": "string",
  "metadata_store_state": "string",
  "identity_state": "string",
  "secrets_state": "string",
  "ready_at": "2019-08-24T14:15:22Z",
  "failed_at": "2019-08-24T14:15:22Z",
  "connection": {
    "host": "string",
    "port": 0,
    "database": "string",
    "username": "string"
  },
  "has_backfill": true,
  "table_suffix": "string"
}

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/data_warehouse/check-database-name/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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.

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/data_warehouse/completed_activity/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

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:read

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/data_warehouse/data_health_issues/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/data_warehouse/data_ops_dashboard/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()