Datasets

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

Endpoints

GET
POST
GET
PATCH
POST
POST
GET
GET
POST
POST
GET
GET

List all datasets

List active datasets by default, or archived datasets when requested.

Required API key scopes

dataset:read

Query parameters

  • archived
    boolean
    Default: false
  • id__in
    array
  • limit
    integer
  • offset
    integer
  • order_by
    string
    Default: -created_at
    One of: "created_at""-created_at""updated_at""-updated_at"
  • search
    string
  • tag_match
    string
    Default: any
    One of: "any""all"
  • tags
    string

Response


Example request

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

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",
      "metadata": {},
      "tags": [
        "string"
      ],
      "archived": true,
      "expires_at": "2019-08-24T14:15:22Z",
      "expiring_soon": true,
      "current_revision": 0,
      "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
      "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"
      },
      "team_id": 0,
      "user_access_level": "string"
    }
  ]
}

Create datasets

Create an empty dataset. Its first revision is created with its first item.

Required API key scopes

dataset:write

Request parameters

  • tags
    array
  • name
    string
  • description
    string
    Default:
  • metadata
    object

Response


Example request

POST /api/projects/:project_id/datasets
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/datasets/\
	-d name="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "expiring_soon": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "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"
  },
  "team_id": 0,
  "user_access_level": "string"
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

Retrieve datasets

Retrieve an active or archived dataset.

Required API key scopes

dataset:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/datasets/: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/datasets/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "expiring_soon": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "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"
  },
  "team_id": 0,
  "user_access_level": "string"
}

Update datasets

Update descriptive dataset fields without changing its revision.

Required API key scopes

dataset:write

Path parameters

  • id
    string

Request parameters

  • tags
    array
  • name
    string
  • description
    string
  • metadata
    object

Response


Example request

PATCH /api/projects/:project_id/datasets/: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/datasets/:id/\
	-d tags="array"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "expiring_soon": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "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"
  },
  "team_id": 0,
  "user_access_level": "string"
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

Create datasets

Archive a dataset. Archived datasets remain readable and reject item mutations.

Required API key scopes

dataset:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/datasets/:id/archive
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/datasets/:id/archive/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "expiring_soon": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "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"
  },
  "team_id": 0,
  "user_access_level": "string"
}

Create datasets exports

Create an asynchronous JSONL export pinned to an immutable dataset revision.

Required API key scopes

dataset:read

Path parameters

  • id
    string

Request parameters

  • revision
    integer

Response


Example request

POST /api/projects/:project_id/datasets/:id/exports
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/datasets/:id/exports/\
	-d revision="integer"

Example response

Status 201
RESPONSE
{
  "id": 0,
  "status": "pending",
  "dataset_revision": 0,
  "filename": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_after": "2019-08-24T14:15:22Z",
  "exception": "string"
}
Status 409
RESPONSE
{
  "detail": "string"
}

Retrieve datasets exports

Check the status of a dataset export created by the current user.

Required API key scopes

dataset:read

Path parameters

  • export_id
    string
  • id
    string

Response


Example request

GET /api/projects/:project_id/datasets/:id/exports/:export_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/datasets/:id/exports/:export_id/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "status": "pending",
  "dataset_revision": 0,
  "filename": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_after": "2019-08-24T14:15:22Z",
  "exception": "string"
}

Retrieve datasets exports content

Download a completed dataset JSONL export.

Required API key scopes

dataset:read

Path parameters

  • export_id
    string
  • id
    string

Example request

GET /api/projects/:project_id/datasets/:id/exports/:export_id/content
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/exports/:export_id/content/

Example response

Status 200
Status 409
RESPONSE
{
  "detail": "string"
}

Create datasets extend retention

Refresh retention for a dataset and optionally one revision, with the same access required to read them.

Required API key scopes

dataset:read

Path parameters

  • id
    string

Request parameters

  • revision
    integer

Response


Example request

POST /api/projects/:project_id/datasets/:id/extend_retention
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/datasets/:id/extend_retention/\
	-d revision="integer"

Example response

Status 200
RESPONSE
{
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_name": "string",
  "dataset_archived": true,
  "revision": 0,
  "expires_at": "2019-08-24T14:15:22Z"
}

Create datasets

Restore an archived dataset without changing its item states.

Required API key scopes

dataset:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/datasets/:id/restore
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/datasets/:id/restore/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "expiring_soon": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "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"
  },
  "team_id": 0,
  "user_access_level": "string"
}

List all datasets revisions

List immutable dataset revisions, newest first.

Required API key scopes

dataset:read

Path parameters

  • id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

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

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",
      "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
      "revision": 0,
      "created_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"
      },
      "team_id": 0,
      "expires_at": "2019-08-24T14:15:22Z",
      "expiring_soon": true
    }
  ]
}

Retrieve datasets retention

Find accessible datasets and older revisions within seven days of expiry without refreshing their retention.

Required API key scopes

dataset:read

Query parameters

  • kind
    string
    Default: datasets
    One of: "datasets""revisions"
  • limit
    integer
    Default: 5
  • offset
    integer
    Default: 0

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "datasets_count": 0,
  "revisions_count": 0,
  "count": 0,
  "results": [
    {
      "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
      "dataset_name": "string",
      "dataset_archived": true,
      "revision": 0,
      "expires_at": "2019-08-24T14:15:22Z"
    }
  ]
}