Persons

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

Endpoints

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

List all persons

You can also use the query endpoint to retrieve persons. It enables you to use SQL to query the persons table.

Required API key scopes

person:read

Path parameters

  • project_id
    string

Query parameters

  • distinct_id
    string
  • email
    string
  • format
    string
    One of: "csv""json"
  • limit
    integer
  • offset
    integer
  • properties
    Click to open
    array
  • search
    string

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "next": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "previous": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "count": 400,
  "results": [
    {
      "id": 0,
      "name": "string",
      "distinct_ids": [
        "string"
      ],
      "properties": null,
      "created_at": "2019-08-24T14:15:22Z",
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
    }
  ]
}

Retrieve persons

Required API key scopes

person:read

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": null,
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Update persons

It is better to use the capture API to update person properties.

This endpoint functionally captures a $set event with a $set property key along with the property values you want to update.

Required API key scopes

person:write

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • properties

Response


Example request

PATCH /api/projects/:project_id/persons/: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/persons/:id/\
	-d name="string"

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": null,
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Delete persons

This is the main way to delete data in PostHog.

To learn more, see our data deletion docs.

Use this endpoint to delete individual persons. For bulk deletion, use the bulk_delete endpoint instead.

Required API key scopes

person:write

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • delete_events
    boolean
    Default: false
  • format
    string
    One of: "csv""json"

Example request

DELETE /api/projects/:project_id/persons/: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/persons/:id/

Example response

Status 204 No response body

Retrieve persons activity retrieve

Required API key scopes

activity_log:read

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Create persons delete events

Queue deletion of all events associated with this person. The task runs during non-peak hours.

Required API key scopes

person:write

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Create persons delete property

It is better to use the capture API to change person properties.

This endpoint functionally captures a $delete_person_property event with an $unset property key along with the property value you want to delete.

Required API key scopes

person:write

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • $unset
    string
  • format
    string
    One of: "csv""json"

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Create persons delete recordings

Queue deletion of all recordings associated with this person.

Required API key scopes

person:write

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Retrieve persons properties timeline

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Create persons split

Required API key scopes

person:write

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Create persons update property

It is better to use the capture API to update person properties.

This endpoint functionally captures a $set event with a $set property key along with the property value you want to update.

Required API key scopes

person:write

Path parameters

  • id
    integer
  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"
  • key
    string
  • value

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Retrieve persons activity

Required API key scopes

activity_log:read

Path parameters

  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Example request

GET /api/projects/:project_id/persons/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/persons/activity/

Example response

Status 200 No response body

Create persons bulk delete

This endpoint allows you to bulk delete persons, either by the PostHog person IDs or by distinct IDs. You can pass in a maximum of 1000 IDs per call.

Required API key scopes

person:write

Path parameters

  • project_id
    string

Query parameters

  • delete_events
    boolean
    Default: false
  • distinct_ids
    object
  • format
    string
    One of: "csv""json"
  • ids
    object

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Retrieve persons cohorts

Required API key scopes

person:readcohort:read

Path parameters

  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Retrieve persons funnel

Path parameters

  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Create persons funnel

Path parameters

  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Retrieve persons funnel correlation

Path parameters

  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Create persons funnel correlation

Path parameters

  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • properties

Example request

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

Example response

Status 200 No response body

Retrieve persons lifecycle

Path parameters

  • project_id
    string

Query parameters

  • format
    string
    One of: "csv""json"

Example request

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

Example response

Status 200 No response body
Next page →

Community questions

Questions about this page? or post a community question.