Persons API Reference

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

To create or update persons, use a PostHog library of your choice and use an identify call. This API endpoint is only for reading and deleting.

Endpoints

`GET`	`/api/projects/:project_id/persons/`
`GET`	`/api/projects/:project_id/persons/:id/`
`PATCH`	`/api/projects/:project_id/persons/:id/`
`DELETE`	`/api/projects/:project_id/persons/:id/`
`GET`	`/api/projects/:project_id/persons/:id/activity/`
`POST`	`/api/projects/:project_id/persons/:id/delete_property/`
`GET`	`/api/projects/:project_id/persons/:id/properties_timeline/`
`POST`	`/api/projects/:project_id/persons/:id/split/`
`POST`	`/api/projects/:project_id/persons/:id/update_property/`
`GET`	`/api/projects/:project_id/persons/activity/`
`GET`	`/api/projects/:project_id/persons/cohorts/`
`GET`	`/api/projects/:project_id/persons/funnel/`
`POST`	`/api/projects/:project_id/persons/funnel/`
`GET`	`/api/projects/:project_id/persons/funnel/correlation/`
`POST`	`/api/projects/:project_id/persons/funnel/correlation/`
`GET`	`/api/projects/:project_id/persons/lifecycle/`
`GET`	`/api/projects/:project_id/persons/path/`
`POST`	`/api/projects/:project_id/persons/path/`
`GET`	`/api/projects/:project_id/persons/properties/`
`GET`	`/api/projects/:project_id/persons/retention/`
`GET`	`/api/projects/:project_id/persons/stickiness/`
`GET`	`/api/projects/:project_id/persons/trends/`
`GET`	`/api/projects/:project_id/persons/values/`

List all persons

Path Parameters

project_id
string

Query Parameters

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

Response

Request

GET /api/projects/:project_id/persons

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/

Response

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",
  "results": [
    {
      "id": 0,
      "name": "string",
      "distinct_ids": [
        "string"
      ],
      "properties": {
        "property1": null,
        "property2": null
      },
      "created_at": "2019-08-24T14:15:22Z",
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
    }
  ]
}

Retrieve persons

Path Parameters

id
integer
project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/

Response

RESPONSE

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

Update persons

Path Parameters

id
integer
project_id
string

Query Parameters

format
string
One of: "csv""json"

Request Parameters

properties
object

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/\
	-d name="string"

Response

RESPONSE

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

Delete persons

Path Parameters

id
integer
project_id
string

Query Parameters

delete_events
boolean
format
string
One of: "csv""json"

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/

Response

No response

Retrieve persons activity retrieve

Path Parameters

id
integer
project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/activity/

Response

RESPONSE

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

Create persons delete property

Path Parameters

id
integer
project_id
string

Query Parameters

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

Request Parameters

properties
object

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/delete_property/\
	-d name="string"

Response

RESPONSE

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

Retrieve persons properties timeline

Path Parameters

id
integer
project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/properties_timeline/

Response

RESPONSE

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

Create persons split

Path Parameters

id
integer
project_id
string

Query Parameters

format
string
One of: "csv""json"

Request Parameters

properties
object

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/split/\
	-d name="string"

Response

RESPONSE

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

Create persons update property

Path Parameters

id
integer
project_id
string

Query Parameters

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

Request Parameters

properties
object

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/:id/update_property/\
	-d name="string"

Response

RESPONSE

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

Retrieve persons activity

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/activity/

Response

RESPONSE

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

Retrieve persons cohorts

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/cohorts/

Response

RESPONSE

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

Retrieve persons funnel

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/funnel/

Response

RESPONSE

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

Create persons funnel

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Request Parameters

properties
object

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/funnel/\
	-d name="string"

Response

RESPONSE

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

Retrieve persons funnel correlation

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/funnel/correlation/

Response

RESPONSE

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

Create persons funnel correlation

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Request Parameters

properties
object

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/funnel/correlation/\
	-d name="string"

Response

RESPONSE

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

Retrieve persons lifecycle

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

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" \
    https://app.posthog.com/api/projects/:project_id/persons/lifecycle/

Response

RESPONSE

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

Retrieve persons path

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

Request

GET /api/projects/:project_id/persons/path

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/path/

Response

RESPONSE

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

Create persons path

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Request Parameters

properties
object

Response

Request

POST /api/projects/:project_id/persons/path

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/path/\
	-d name="string"

Response

RESPONSE

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

Retrieve persons properties

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

Request

GET /api/projects/:project_id/persons/properties

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/properties/

Response

RESPONSE

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

Retrieve persons retention

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

Request

GET /api/projects/:project_id/persons/retention

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/retention/

Response

RESPONSE

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

Retrieve persons stickiness

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

Request

GET /api/projects/:project_id/persons/stickiness

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/stickiness/

Response

RESPONSE

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

Retrieve persons trends

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

Request

GET /api/projects/:project_id/persons/trends

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/trends/

Response

RESPONSE

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

Retrieve persons values

Path Parameters

project_id
string

Query Parameters

format
string
One of: "csv""json"

Response

Request

GET /api/projects/:project_id/persons/values

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/persons/values/

Response

RESPONSE

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