Event definitions API Reference

Event definitions

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

Endpoints

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

List all event definitions

Required API key scopes

event_definition:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/event_definitions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/event_definitions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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",
      "owner": 0,
      "description": "string",
      "tags": [
        null
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "updated_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"
      },
      "last_seen_at": "2019-08-24T14:15:22Z",
      "last_updated_at": "2019-08-24T14:15:22Z",
      "verified": true,
      "verified_at": "2019-08-24T14:15:22Z",
      "verified_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"
      },
      "hidden": true,
      "enforcement_mode": "allow",
      "promoted_property": "string",
      "is_action": true,
      "action_id": 0,
      "is_calculating": true,
      "last_calculated_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"
      },
      "post_to_slack": false,
      "default_columns": [
        "string"
      ],
      "media_preview_urls": [
        "string"
      ]
    }
  ]
}

Create event definitions

Required API key scopes

event_definition:write

Request parameters

name
string
owner
integer
description
string
tags
array
verified
boolean
hidden
boolean
enforcement_mode
promoted_property
string
post_to_slack
boolean
Default: false
default_columns
array

Response

Example request

POST /api/projects/:project_id/event_definitions
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/event_definitions/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "owner": 0,
  "description": "string",
  "tags": [
    null
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_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"
  },
  "last_seen_at": "2019-08-24T14:15:22Z",
  "last_updated_at": "2019-08-24T14:15:22Z",
  "verified": true,
  "verified_at": "2019-08-24T14:15:22Z",
  "verified_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"
  },
  "hidden": true,
  "enforcement_mode": "allow",
  "promoted_property": "string",
  "is_action": true,
  "action_id": 0,
  "is_calculating": true,
  "last_calculated_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"
  },
  "post_to_slack": false,
  "default_columns": [
    "string"
  ],
  "media_preview_urls": [
    "string"
  ]
}

Retrieve event definitions

Required API key scopes

event_definition:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/event_definitions/: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/event_definitions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/{event_definition_id}/".format(
        project_id=project_id,
		event_definition_id="<the event definition id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "owner": 0,
  "description": "string",
  "tags": [
    null
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_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"
  },
  "last_seen_at": "2019-08-24T14:15:22Z",
  "last_updated_at": "2019-08-24T14:15:22Z",
  "verified": true,
  "verified_at": "2019-08-24T14:15:22Z",
  "verified_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"
  },
  "hidden": true,
  "enforcement_mode": "allow",
  "promoted_property": "string",
  "is_action": true,
  "action_id": 0,
  "is_calculating": true,
  "last_calculated_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"
  },
  "post_to_slack": false,
  "default_columns": [
    "string"
  ],
  "media_preview_urls": [
    "string"
  ]
}

Update event definitions

Required API key scopes

event_definition:write

Path parameters

id
string

Request parameters

name
string
owner
integer
description
string
tags
array
verified
boolean
hidden
boolean
enforcement_mode
promoted_property
string
post_to_slack
boolean
Default: false
default_columns
array

Response

Example request

PATCH /api/projects/:project_id/event_definitions/: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/event_definitions/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/{event_definition_id}/".format(
        project_id=project_id,
		event_definition_id="<the event definition id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "owner": 0,
  "description": "string",
  "tags": [
    null
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_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"
  },
  "last_seen_at": "2019-08-24T14:15:22Z",
  "last_updated_at": "2019-08-24T14:15:22Z",
  "verified": true,
  "verified_at": "2019-08-24T14:15:22Z",
  "verified_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"
  },
  "hidden": true,
  "enforcement_mode": "allow",
  "promoted_property": "string",
  "is_action": true,
  "action_id": 0,
  "is_calculating": true,
  "last_calculated_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"
  },
  "post_to_slack": false,
  "default_columns": [
    "string"
  ],
  "media_preview_urls": [
    "string"
  ]
}

Delete event definitions

Required API key scopes

event_definition:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/event_definitions/: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/event_definitions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/{event_definition_id}/".format(
        project_id=project_id,
		event_definition_id="<the event definition id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Retrieve event definitions metrics

Path parameters

id
string

Example request

GET /api/projects/:project_id/event_definitions/:id/metrics
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/event_definitions/:id/metrics/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/{event_definition_id}/metrics/".format(
        project_id=project_id,
		event_definition_id="<the event definition id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create event definitions bulk update tags

Bulk update tags on multiple objects.

Accepts:

{"ids": [...], "action": "add"|"remove"|"set", "tags": ["tag1", "tag2"]}

Actions:

"add": Add tags to existing tags on each object
"remove": Remove specific tags from each object
"set": Replace all tags on each object with the provided list

Request parameters

ids
array
action
tags
array

Response

Example request

POST /api/projects/:project_id/event_definitions/bulk_update_tags
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/event_definitions/bulk_update_tags/\
	-d ids="array",\
	-d action=undefined,\
	-d tags="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/bulk_update_tags/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array",
		"tags": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "updated": [
    {
      "id": 0,
      "tags": [
        "string"
      ]
    }
  ],
  "skipped": [
    {
      "id": 0,
      "reason": "string"
    }
  ]
}

Retrieve event definitions by name

Get event definition by exact name

Required API key scopes

event_definition:read

Query parameters

name
string

Response

Example request

GET /api/projects/:project_id/event_definitions/by_name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/event_definitions/by_name/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/by_name/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "last_seen_at": "2019-08-24T14:15:22Z",
  "last_updated_at": "2019-08-24T14:15:22Z",
  "tags": [
    null
  ],
  "enforcement_mode": "allow",
  "promoted_property": "string",
  "is_action": true,
  "action_id": 0,
  "is_calculating": true,
  "last_calculated_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"
  },
  "post_to_slack": false
}

Retrieve event definitions golang

Required API key scopes

event_definition:read

Example request

GET /api/projects/:project_id/event_definitions/golang
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/event_definitions/golang/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/golang/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve event definitions promoted properties

Resolve team-configured promoted properties for event definitions.

The response only contains entries where a non-null promoted_property is set on the EventDefinition. Callers should fall back to the core taxonomy defaults client-side for names not present in the response.

Required API key scopes

event_definition:read

Query parameters

names
array

Response

Example request

GET /api/projects/:project_id/event_definitions/promoted_properties
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/event_definitions/promoted_properties/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/promoted_properties/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "promoted_properties": {
    "property1": "string",
    "property2": "string"
  }
}

Retrieve event definitions python

Required API key scopes

event_definition:read

Example request

GET /api/projects/:project_id/event_definitions/python
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/event_definitions/python/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/python/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve event definitions typescript

Required API key scopes

event_definition:read

Example request

GET /api/projects/:project_id/event_definitions/typescript
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/event_definitions/typescript/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/event_definitions/typescript/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Event definitions

Endpoints

List all event definitions

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create event definitions

Required API key scopes

Request parameters

Response

Example request

Example response

Status 201

Retrieve event definitions

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Update event definitions

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Delete event definitions

Required API key scopes

Path parameters

Example request

Example response

Status 204 No response body

Retrieve event definitions metrics

Path parameters

Example request

Example response

Status 200 No response body

Create event definitions bulk update tags

Request parameters

Response

Example request

Example response

Status 200

Retrieve event definitions by name

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Retrieve event definitions golang

Required API key scopes

Example request

Example response

Status 200 No response body

Retrieve event definitions promoted properties

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Retrieve event definitions python

Required API key scopes

Example request

Example response

Status 200 No response body

Retrieve event definitions typescript

Required API key scopes

Example request

Example response

Status 200 No response body

Community questions