Environments-23 API Reference

Environments-23

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

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Endpoints

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

Retrieve environments persons lifecycle

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/: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/environments/:project_id/persons/lifecycle/

Example response

Status 200 No response body

Create environments persons reset person distinct id

Reset a distinct_id for a deleted person. This allows the distinct_id to be used again.

Required API key scopes

person:write

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:project_id/persons/reset_person_distinct_id

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/environments/:project_id/persons/reset_person_distinct_id/\
	-d name="string"

Example response

Status 200 No response body

Create environments persons reset person distinct id

Reset a distinct_id for a deleted person. This allows the distinct_id to be used again.

Required API key scopes

person:write

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:project_id/persons/reset_person_distinct_id

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/environments/:project_id/persons/reset_person_distinct_id/\
	-d name="string"

Example response

Status 200 No response body

Retrieve environments persons stickiness

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:project_id/persons/stickiness

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

Example response

Status 200 No response body

Retrieve environments persons stickiness

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:project_id/persons/stickiness

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

Example response

Status 200 No response body

Retrieve environments persons trends

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:project_id/persons/trends

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

Example response

Status 200 No response body

Retrieve environments persons trends

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:project_id/persons/trends

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

Example response

Status 200 No response body

Retrieve environments persons values

Required API key scopes

person:read

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:project_id/persons/values

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

Example response

Status 200 No response body

Retrieve environments persons values

Required API key scopes

person:read

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:project_id/persons/values

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

Example response

Status 200 No response body

List all environments plugin configs logs

Required API key scopes

plugin:read

Path parameters

plugin_config_id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

limit
integer
Number of results to return per page.
offset
integer
The initial index from which to return the results.

Response

Example request

GET /api/environments/:project_id/plugin_configs/:plugin_config_id/logs

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/plugin_configs/:plugin_config_id/logs/

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",
      "team_id": 0,
      "plugin_id": 0,
      "plugin_config_id": 0,
      "timestamp": "2019-08-24T14:15:22Z",
      "source": "SYSTEM",
      "type": "DEBUG",
      "message": "string",
      "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366"
    }
  ]
}

List all environments plugin configs logs

Required API key scopes

plugin:read

Path parameters

plugin_config_id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

limit
integer
Number of results to return per page.
offset
integer
The initial index from which to return the results.

Response

Example request

GET /api/environments/:project_id/plugin_configs/:plugin_config_id/logs

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/plugin_configs/:plugin_config_id/logs/

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",
      "team_id": 0,
      "plugin_id": 0,
      "plugin_config_id": 0,
      "timestamp": "2019-08-24T14:15:22Z",
      "source": "SYSTEM",
      "type": "DEBUG",
      "message": "string",
      "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366"
    }
  ]
}

Create environments query

Required API key scopes

query:read

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request parameters

async
client_query_id
Client provided query ID. Can be used to retrieve the status or cancel the query.
filters_override
name
Name given to a query. It's used to identify the query in the UI. Up to 128 characters for a name.
query
Submit a JSON string representing a query for PostHog data analysis, for example a HogQL query.

Example payload:
```
{"query": {"kind": "HogQLQuery", "query": "select * from events limit 100"}}
```
For more details on HogQL queries, see the PostHog HogQL documentation.
refresh
Default: blocking
Whether results should be calculated sync or async, and how much to rely on the cache:
- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache
- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache
- 'lazy_async' - kick off background calculation, UNLESS there are somewhat fresh results in the cache
- 'force_blocking' - calculate synchronously, even if fresh results are already cached
- 'force_async' - kick off background calculation, even if fresh results are already cached
- 'force_cache' - return cached data or a cache miss; always completes immediately as it never calculates Background calculation can be tracked using the query_status response field.
variables_override

Response

Example request

POST /api/environments/:project_id/query

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/environments/:project_id/query/\
	-d query=undefined

Example response

Status 200

RESPONSE

{}

Create environments query

Required API key scopes

query:read

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request parameters

async
client_query_id
Client provided query ID. Can be used to retrieve the status or cancel the query.
filters_override
name
Name given to a query. It's used to identify the query in the UI. Up to 128 characters for a name.
query
Submit a JSON string representing a query for PostHog data analysis, for example a HogQL query.

Example payload:
```
{"query": {"kind": "HogQLQuery", "query": "select * from events limit 100"}}
```
For more details on HogQL queries, see the PostHog HogQL documentation.
refresh
Default: blocking
Whether results should be calculated sync or async, and how much to rely on the cache:
- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache
- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache
- 'lazy_async' - kick off background calculation, UNLESS there are somewhat fresh results in the cache
- 'force_blocking' - calculate synchronously, even if fresh results are already cached
- 'force_async' - kick off background calculation, even if fresh results are already cached
- 'force_cache' - return cached data or a cache miss; always completes immediately as it never calculates Background calculation can be tracked using the query_status response field.
variables_override

Response

Example request

POST /api/environments/:project_id/query

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/environments/:project_id/query/\
	-d query=undefined

Example response

Status 200

RESPONSE

{}

Retrieve environments query

(Experimental)

Required API key scopes

query:read

Path parameters

id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Response

Example request

GET /api/environments/:project_id/query/:id

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

Example response

Status 200

RESPONSE

{
  "query_status": {
    "complete": false,
    "dashboard_id": null,
    "end_time": null,
    "error": false,
    "error_message": null,
    "expiration_time": null,
    "id": "string",
    "insight_id": null,
    "labels": null,
    "pickup_time": null,
    "query_async": true,
    "query_progress": null,
    "results": null,
    "start_time": null,
    "task_id": null,
    "team_id": 0
  }
}

Retrieve environments query

(Experimental)

Required API key scopes

query:read

Path parameters

id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Response

Example request

GET /api/environments/:project_id/query/:id

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

Example response

Status 200

RESPONSE

{
  "query_status": {
    "complete": false,
    "dashboard_id": null,
    "end_time": null,
    "error": false,
    "error_message": null,
    "expiration_time": null,
    "id": "string",
    "insight_id": null,
    "labels": null,
    "pickup_time": null,
    "query_async": true,
    "query_progress": null,
    "results": null,
    "start_time": null,
    "task_id": null,
    "team_id": 0
  }
}

Delete environments query

(Experimental)

Required API key scopes

query:read

Path parameters

id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

DELETE /api/environments/:project_id/query/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/query/:id/

Example response

Status 204 Query cancelled

Delete environments query

(Experimental)

Required API key scopes

query:read

Path parameters

id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

DELETE /api/environments/:project_id/query/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/query/:id/

Example response

Status 204 Query cancelled

Retrieve environments query log

Get query log details from query_log_archive table for a specific query_id, the query must have been issued in last 24 hours.

Path parameters

id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

GET /api/environments/:project_id/query/:id/log

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/query/:id/log/

Example response

Status 200

Retrieve environments query log

Get query log details from query_log_archive table for a specific query_id, the query must have been issued in last 24 hours.

Path parameters

id
string
project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

GET /api/environments/:project_id/query/:id/log

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/query/:id/log/

Example response

Status 200

Create environments query check auth for async

Path parameters

project_id
string
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

POST /api/environments/:project_id/query/check_auth_for_async

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/environments/:project_id/query/check_auth_for_async/