External Data

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

Endpoints

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

List all external data schemas

Also available via the PostHog MCP server:
external-data-schemas-list — List data warehouse table schemas (imported tables)

Required API key scopes

external_data_source:read

Query parameters

limit
integer
offset
integer
search
string

Response

Example request

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

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",
      "label": "string",
      "table": {},
      "should_sync": true,
      "last_synced_at": "2019-08-24T14:15:22Z",
      "latest_error": "string",
      "incremental": true,
      "status": "string",
      "sync_type": "full_refresh",
      "incremental_field": "string",
      "incremental_field_type": "integer",
      "incremental_field_lookback_seconds": 5184000,
      "sync_frequency": "never",
      "sync_time_of_day": "14:15:22Z",
      "description": "string",
      "primary_key_columns": [
        "string"
      ],
      "cdc_table_mode": "consolidated",
      "enabled_columns": [
        "string"
      ],
      "row_filters": [
        {
          "column": "string",
          "operator": "string",
          "value": null
        }
      ],
      "available_columns": [
        {
          "name": "string",
          "data_type": "string",
          "is_nullable": true
        }
      ],
      "source_column_metadata_available": true,
      "source": {
        "id": "string",
        "source_type": "string",
        "access_method": "string",
        "supports_column_selection": true,
        "supports_row_filters": true,
        "requires_exact_column_metadata": true,
        "user_access_level": "string",
        "api_version": "string",
        "supported_api_versions": [
          "string"
        ]
      },
      "api_version": "string",
      "api_version_deprecation": {
        "version": "string",
        "sunset_at": "2019-08-24",
        "default_version": "string"
      },
      "user_access_level": "string"
    }
  ]
}

Retrieve external data schemas

Also available via the PostHog MCP server:
external-data-schemas-retrieve — Get data warehouse table schema

Required API key scopes

external_data_source:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/external_data_schemas/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/external_data_schemas/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "label": "string",
  "table": {},
  "should_sync": true,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "latest_error": "string",
  "incremental": true,
  "status": "string",
  "sync_type": "full_refresh",
  "incremental_field": "string",
  "incremental_field_type": "integer",
  "incremental_field_lookback_seconds": 5184000,
  "sync_frequency": "never",
  "sync_time_of_day": "14:15:22Z",
  "description": "string",
  "primary_key_columns": [
    "string"
  ],
  "cdc_table_mode": "consolidated",
  "enabled_columns": [
    "string"
  ],
  "row_filters": [
    {
      "column": "string",
      "operator": "string",
      "value": null
    }
  ],
  "available_columns": [
    {
      "name": "string",
      "data_type": "string",
      "is_nullable": true
    }
  ],
  "source_column_metadata_available": true,
  "source": {
    "id": "string",
    "source_type": "string",
    "access_method": "string",
    "supports_column_selection": true,
    "supports_row_filters": true,
    "requires_exact_column_metadata": true,
    "user_access_level": "string",
    "api_version": "string",
    "supported_api_versions": [
      "string"
    ]
  },
  "api_version": "string",
  "api_version_deprecation": {
    "version": "string",
    "sunset_at": "2019-08-24",
    "default_version": "string"
  },
  "user_access_level": "string"
}

Update external data schemas

Also available via the PostHog MCP server:
external-data-schemas-partial-update — Update data warehouse table schema sync config

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

should_sync
boolean
sync_type
incremental_field
stringnull
incremental_field_type
incremental_field_lookback_seconds
integernull
sync_frequency
sync_time_of_day
stringnull
primary_key_columns
arraynull
cdc_table_mode
enabled_columns
arraynull
row_filters
arraynull
api_version
stringnull

Response

Example request

PATCH /api/projects/:project_id/external_data_schemas/:id
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/external_data_schemas/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "label": "string",
  "table": {},
  "should_sync": true,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "latest_error": "string",
  "incremental": true,
  "status": "string",
  "sync_type": "full_refresh",
  "incremental_field": "string",
  "incremental_field_type": "integer",
  "incremental_field_lookback_seconds": 5184000,
  "sync_frequency": "never",
  "sync_time_of_day": "14:15:22Z",
  "description": "string",
  "primary_key_columns": [
    "string"
  ],
  "cdc_table_mode": "consolidated",
  "enabled_columns": [
    "string"
  ],
  "row_filters": [
    {
      "column": "string",
      "operator": "string",
      "value": null
    }
  ],
  "available_columns": [
    {
      "name": "string",
      "data_type": "string",
      "is_nullable": true
    }
  ],
  "source_column_metadata_available": true,
  "source": {
    "id": "string",
    "source_type": "string",
    "access_method": "string",
    "supports_column_selection": true,
    "supports_row_filters": true,
    "requires_exact_column_metadata": true,
    "user_access_level": "string",
    "api_version": "string",
    "supported_api_versions": [
      "string"
    ]
  },
  "api_version": "string",
  "api_version_deprecation": {
    "version": "string",
    "sunset_at": "2019-08-24",
    "default_version": "string"
  },
  "user_access_level": "string"
}

Delete external data schemas

Required API key scopes

external_data_source:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/external_data_schemas/: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/external_data_schemas/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create external data schemas cancel

Required API key scopes

external_data_source:write

Path parameters

id
string

Example request

POST /api/projects/:project_id/external_data_schemas/:id/cancel
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/external_data_schemas/:id/cancel/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/cancel/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 The running sync was cancelled. v3 pipeline jobs are marked Failed immediately; for older pipeline versions the cancelled workflow records the final status. When no sync was actually running but the schema was stuck reporting Running, the schema status is corrected instead and the response says so.

Status 400 No running sync to cancel, or the sync already finished.

Delete external data schemas delete data

Required API key scopes

external_data_source:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/external_data_schemas/:id/delete_data
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/external_data_schemas/:id/delete_data/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/delete_data/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Retrieve external data schemas destinations

Read or replace this table's destination override.

Send destination_ids: null to clear the override so the table follows its source again.

Required API key scopes

external_data_source:write

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/external_data_schemas/:id/destinations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/external_data_schemas/:id/destinations/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/destinations/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "destination_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "inherits_from_source": true,
  "effective_destination_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Update external data schemas destinations

Read or replace this table's destination override.

Send destination_ids: null to clear the override so the table follows its source again.

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

destination_ids
arraynull

Response

Example request

PATCH /api/projects/:project_id/external_data_schemas/:id/destinations
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/external_data_schemas/:id/destinations/\
	-d destination_ids=["array","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/destinations/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"destination_ids": [
			"array",
			"null"
		]
	}
).json()

Example response

Status 200

RESPONSE
{
  "destination_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "inherits_from_source": true,
  "effective_destination_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Create external data schemas incremental fields

Also available via the PostHog MCP server:
external-data-schemas-incremental-fields-create — Refresh candidate incremental fields for a schema

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

should_sync
boolean
sync_type
incremental_field
stringnull
incremental_field_type
incremental_field_lookback_seconds
integernull
sync_frequency
sync_time_of_day
stringnull
primary_key_columns
arraynull
cdc_table_mode
enabled_columns
arraynull
row_filters
arraynull
api_version
stringnull

Example request

POST /api/projects/:project_id/external_data_schemas/:id/incremental_fields
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/external_data_schemas/:id/incremental_fields/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/incremental_fields/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve external data schemas logs

Required API key scopes

external_data_source:read

Path parameters

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

Example response

Status 200 No response body

Create external data schemas reload

Trigger a sync for the schema using its configured sync method. Most methods keep the existing warehouse table and add or merge new rows, but a full-refresh schema rebuilds the whole table on every run. To force a rebuild from the source, use resync.

Required API key scopes

external_data_source:write

Path parameters

id
string

Example request

POST /api/projects/:project_id/external_data_schemas/:id/reload
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/external_data_schemas/:id/reload/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/reload/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 The sync was triggered.

Status 400 The sync could not be started.

Create external data schemas resync

Request a full resync of the schema. For sources that can backfill, this drops the warehouse table and re-imports every row from the source, so existing data is deleted first. A webhook-only schema cannot backfill, so it keeps its existing table and resumes ingestion instead. To sync without requesting a rebuild, use reload.

Required API key scopes

external_data_source:write

Path parameters

id
string

Example request

POST /api/projects/:project_id/external_data_schemas/:id/resync
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/external_data_schemas/:id/resync/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/external_data_schemas/{external_data_schema_id}/resync/".format(
        project_id=project_id,
		external_data_schema_id="<the external data schema id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()