Dataset items

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

Endpoints

GET
POST
GET
PATCH
POST
POST
GET

List all dataset items

List a dataset's current items or its exact contents at a prior revision.

Required API key scopes

dataset:read

Query parameters

  • archived
    boolean
    Default: false
  • dataset
    string
  • limit
    integer
  • offset
    integer
  • revision
    integer

Response


Example request

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

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": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
      "client_item_id": "string",
      "version": 0,
      "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
      "dataset_revision": 0,
      "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
      "archived": true,
      "input": {},
      "expected_output": {},
      "source_output": {},
      "metadata": {},
      "source_trace_id": "string",
      "source_event_id": "string",
      "source_timestamp": "2019-08-24T14:15:22Z",
      "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"
      },
      "version_created_at": "2019-08-24T14:15:22Z",
      "version_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
    }
  ]
}

Create dataset items

Create an item and its first immutable version. An identical client item ID retry returns the existing item. A different payload or an archived match returns a conflict.

Required API key scopes

dataset:write

Request parameters

  • dataset
    string
  • client_item_id
    stringnull
  • input
  • expected_output
  • source_output
  • metadata
    object
  • source_trace_id
    stringnull
  • source_event_id
    stringnull
  • source_timestamp
    stringnull

Response


Example request

POST /api/projects/:project_id/dataset_items
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/dataset_items/\
	-d dataset="string",\
	-d input=undefined

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "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"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_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
}
Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "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"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_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
}
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 dataset items

Retrieve the current item version or the version visible at an exact dataset revision.

Required API key scopes

dataset:read

Path parameters

  • dataset_item_id
    string

Query parameters

  • revision
    integer

Response


Example request

GET /api/projects/:project_id/dataset_items/:dataset_item_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/dataset_items/:dataset_item_id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "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"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_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
}

Update dataset items

Create a new immutable item version from editable fields.

Required API key scopes

dataset:write

Path parameters

  • dataset_item_id
    string

Response


Example request

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "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"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_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
}
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 dataset items

Archive an active item by creating a new immutable version.

Required API key scopes

dataset:write

Path parameters

  • dataset_item_id
    string

Request parameters

  • base_version
    integer

Response


Example request

POST /api/projects/:project_id/dataset_items/:dataset_item_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/dataset_items/:dataset_item_id/archive/\
	-d base_version="integer"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "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"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_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
}
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 dataset items

Restore an archived item by copying content into a new immutable version.

Required API key scopes

dataset:write

Path parameters

  • dataset_item_id
    string

Request parameters

  • base_version
    integer
  • source_version
    integernull

Response


Example request

POST /api/projects/:project_id/dataset_items/:dataset_item_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/dataset_items/:dataset_item_id/restore/\
	-d base_version="integer"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "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"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_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
}
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
}

List all dataset items versions

List every immutable version of an item, newest first.

Required API key scopes

dataset:read

Path parameters

  • dataset_item_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

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

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": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
      "client_item_id": "string",
      "version": 0,
      "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
      "dataset_revision": 0,
      "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
      "archived": true,
      "input": {},
      "expected_output": {},
      "source_output": {},
      "metadata": {},
      "source_trace_id": "string",
      "source_event_id": "string",
      "source_timestamp": "2019-08-24T14:15:22Z",
      "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"
      },
      "version_created_at": "2019-08-24T14:15:22Z",
      "version_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
    }
  ]
}