Warehouse

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

Endpoints

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

List all warehouse tables

Create, Read, Update and Delete Warehouse Tables.

Required API key scopes

warehouse_table:read

Query parameters

limit
integer
offset
integer
search
string

Response

Example request

GET /api/projects/:project_id/warehouse_tables
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/warehouse_tables/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/warehouse_tables/".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",
      "deleted": true,
      "name": "string",
      "hogql_name": "string",
      "format": "CSV",
      "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"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "created_via": "web",
      "url_pattern": "string",
      "credential": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "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"
        },
        "created_at": "2019-08-24T14:15:22Z",
        "access_key": "string",
        "access_secret": "string"
      },
      "columns": [
        {}
      ],
      "external_data_source": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "created_at": "2019-08-24T14:15:22Z",
        "created_by": 0,
        "status": "string",
        "source_type": "Ashby"
      },
      "external_schema": {},
      "options": {},
      "user_access_level": "string"
    }
  ]
}

Create warehouse tables

Create, Read, Update and Delete Warehouse Tables.

Required API key scopes

warehouse_table:write

Request parameters

deleted
boolean | null
name
string
format
url_pattern
string
credential
options
object

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "deleted": true,
  "name": "string",
  "hogql_name": "string",
  "format": "CSV",
  "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_via": "web",
  "url_pattern": "string",
  "credential": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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"
    },
    "created_at": "2019-08-24T14:15:22Z",
    "access_key": "string",
    "access_secret": "string"
  },
  "columns": [
    {}
  ],
  "external_data_source": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": 0,
    "status": "string",
    "source_type": "Ashby"
  },
  "external_schema": {},
  "options": {},
  "user_access_level": "string"
}

Retrieve warehouse tables

Create, Read, Update and Delete Warehouse Tables.

Required API key scopes

warehouse_table:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "deleted": true,
  "name": "string",
  "hogql_name": "string",
  "format": "CSV",
  "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_via": "web",
  "url_pattern": "string",
  "credential": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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"
    },
    "created_at": "2019-08-24T14:15:22Z",
    "access_key": "string",
    "access_secret": "string"
  },
  "columns": [
    {}
  ],
  "external_data_source": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": 0,
    "status": "string",
    "source_type": "Ashby"
  },
  "external_schema": {},
  "options": {},
  "user_access_level": "string"
}

Update warehouse tables

Create, Read, Update and Delete Warehouse Tables.

Required API key scopes

warehouse_table:write

Path parameters

id
string

Request parameters

deleted
boolean | null
name
string
format
url_pattern
string
credential
options
object

Response

Example request

PATCH /api/projects/:project_id/warehouse_tables/: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/warehouse_tables/:id/\
	-d deleted="boolean"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/warehouse_tables/{warehouse_table_id}/".format(
        project_id=project_id,
		warehouse_table_id="<the warehouse table id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"deleted": "boolean"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "deleted": true,
  "name": "string",
  "hogql_name": "string",
  "format": "CSV",
  "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_via": "web",
  "url_pattern": "string",
  "credential": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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"
    },
    "created_at": "2019-08-24T14:15:22Z",
    "access_key": "string",
    "access_secret": "string"
  },
  "columns": [
    {}
  ],
  "external_data_source": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": 0,
    "status": "string",
    "source_type": "Ashby"
  },
  "external_schema": {},
  "options": {},
  "user_access_level": "string"
}

Delete warehouse tables

Create, Read, Update and Delete Warehouse Tables.

Required API key scopes

warehouse_table:write

Path parameters

id
string

Example request

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

Example response

Status 204 No response body

Create warehouse tables refresh schema

Re-introspect a self-managed (manually linked) warehouse table's schema from its underlying source files and overwrite its stored column list. Use when the source schema has evolved (e.g. new columns in the underlying Delta/Parquet/CSV files) but queries still can't see the new columns, because PostHog serves a cached column snapshot until the table is refreshed. Not for tables managed by an external data source sync — those refresh on their own schedule.

Required API key scopes

warehouse_table:write

Path parameters

id
string

Example request

POST /api/projects/:project_id/warehouse_tables/:id/refresh_schema
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/warehouse_tables/:id/refresh_schema/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/warehouse_tables/{warehouse_table_id}/refresh_schema/".format(
        project_id=project_id,
		warehouse_table_id="<the warehouse table id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Schema refreshed from the table's underlying source

Create warehouse tables replace file

Point a table made from an uploaded file at a new upload, then import it with one full refresh. Upload the new file with upload_file first. The table keeps its id and its name, and its rows are replaced when the sync finishes. The old file is deleted only after that sync succeeds. The sync bills its rows like any other import.

Required API key scopes

warehouse_table:write

Path parameters

id
string

Request parameters

upload_id
string
filename
string
file_format

Response

Example request

POST /api/projects/:project_id/warehouse_tables/:id/replace_file
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/warehouse_tables/:id/replace_file/\
	-d upload_id="string",\
	-d filename="string",\
	-d file_format=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/warehouse_tables/{warehouse_table_id}/replace_file/".format(
        project_id=project_id,
		warehouse_table_id="<the warehouse table id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"upload_id": "string",
		"filename": "string"
	}
).json()

Example response

Status 202

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "deleted": true,
  "name": "string",
  "hogql_name": "string",
  "format": "CSV",
  "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_via": "web",
  "url_pattern": "string",
  "credential": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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"
    },
    "created_at": "2019-08-24T14:15:22Z",
    "access_key": "string",
    "access_secret": "string"
  },
  "columns": [
    {}
  ],
  "external_data_source": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": 0,
    "status": "string",
    "source_type": "Ashby"
  },
  "external_schema": {},
  "options": {},
  "user_access_level": "string"
}

Create warehouse tables update schema

Create, Read, Update and Delete Warehouse Tables.

Path parameters

id
string

Request parameters

deleted
boolean | null
name
string
format
url_pattern
string
credential
options
object

Example request

POST /api/projects/:project_id/warehouse_tables/:id/update_schema
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/warehouse_tables/:id/update_schema/\
	-d name="string",\
	-d format=undefined,\
	-d url_pattern="string",\
	-d credential=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/warehouse_tables/{warehouse_table_id}/update_schema/".format(
        project_id=project_id,
		warehouse_table_id="<the warehouse table id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string",
		"url_pattern": "string"
	}
).json()

Example response

Status 200 No response body

Create warehouse tables create from upload

Turn a previously uploaded file into a self-managed warehouse table.

The file already sits in PostHog's own bucket (see upload_file), so the table points straight at it and is read in place — no import pipeline and no recurring sync, the same shape as a linked S3/GCS bucket. The read location is always derived from the caller's own team, so a client-supplied upload_id can only resolve inside that team's folder, and the table carries no credential (reads fall back to the node role, never a user-supplied key).

For a team with object storage sources, the table also gets a file upload source. Its first sync imports the file and turns the same table row into a managed table.

Required API key scopes

warehouse_table:write

Request parameters

upload_id
string
filename
string
file_format
table_name
string

Response

Example request

POST /api/projects/:project_id/warehouse_tables/create_from_upload
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/warehouse_tables/create_from_upload/\
	-d upload_id="string",\
	-d filename="string",\
	-d file_format=undefined,\
	-d table_name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/warehouse_tables/create_from_upload/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"upload_id": "string",
		"filename": "string",
		"table_name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "deleted": true,
  "name": "string",
  "hogql_name": "string",
  "format": "CSV",
  "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "created_via": "web",
  "url_pattern": "string",
  "credential": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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"
    },
    "created_at": "2019-08-24T14:15:22Z",
    "access_key": "string",
    "access_secret": "string"
  },
  "columns": [
    {}
  ],
  "external_data_source": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": 0,
    "status": "string",
    "source_type": "Ashby"
  },
  "external_schema": {},
  "options": {},
  "user_access_level": "string"
}

Create warehouse tables file

Create, Read, Update and Delete Warehouse Tables.

Required API key scopes

warehouse_table:write

Example request

Example response

Status 200 No response body

Create warehouse tables upload file

Store an uploaded file in object storage so a self-managed table can be created from it.

Uploading is a separate first step from create_from_upload so the create call stays JSON-only: this returns an upload_id the caller passes back to build the table. The file is written under a team-scoped prefix, so a table can only ever read back its own team's uploads.

Required API key scopes

warehouse_table:write

Response

Example request

Example response

Status 201

RESPONSE
{
  "upload_id": "f2ef591b-135b-46fa-a604-3d4fda5bfbfb",
  "filename": "string",
  "file_format": "string",
  "size_bytes": 0
}