Custom Property

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

Endpoints

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

List all custom property sources

Required API key scopes

account:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/custom_property_sources
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/custom_property_sources/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/custom_property_sources/".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",
      "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
      "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
      "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
      "source_column": "string",
      "column_property_map": null,
      "column_descriptions": null,
      "key_column": "string",
      "is_enabled": true,
      "consecutive_failures": 0,
      "last_synced_at": "2019-08-24T14:15:22Z",
      "last_sync_error": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": 0,
      "updated_at": "2019-08-24T14:15:22Z",
      "sync_frequency_interval_seconds": 0,
      "next_sync_at": "2019-08-24T14:15:22Z",
      "latest_run": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "job_id": "string",
        "account_segment": "tracked",
        "sync_phase": "staging",
        "attempt": 0,
        "workflow_id": "string",
        "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952",
        "temporal_url": "http://example.com",
        "trigger": "string",
        "status": "string",
        "started_at": "2019-08-24T14:15:22Z",
        "finished_at": "2019-08-24T14:15:22Z",
        "rows_read": 0,
        "changed": 0,
        "existing": 0,
        "produced": 0,
        "skipped_missing_person": 0,
        "error": "string",
        "created_at": "2019-08-24T14:15:22Z"
      },
      "external_data_source": "8df47340-930c-47e2-b1d9-b1b8d55c351d",
      "table_name": "string",
      "saved_query_name": "string"
    }
  ]
}

Create custom property sources

Required API key scopes

account:write

Request parameters

definition
string
saved_query
string | null
external_data_schema
string | null
source_column
string | null
column_property_map
column_descriptions
key_column
string
is_enabled
boolean
Default: true

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
  "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
  "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
  "source_column": "string",
  "column_property_map": null,
  "column_descriptions": null,
  "key_column": "string",
  "is_enabled": true,
  "consecutive_failures": 0,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "last_sync_error": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "sync_frequency_interval_seconds": 0,
  "next_sync_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "job_id": "string",
    "account_segment": "tracked",
    "sync_phase": "staging",
    "attempt": 0,
    "workflow_id": "string",
    "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952",
    "temporal_url": "http://example.com",
    "trigger": "string",
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "rows_read": 0,
    "changed": 0,
    "existing": 0,
    "produced": 0,
    "skipped_missing_person": 0,
    "error": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "external_data_source": "8df47340-930c-47e2-b1d9-b1b8d55c351d",
  "table_name": "string",
  "saved_query_name": "string"
}

Retrieve custom property sources

Required API key scopes

account:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
  "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
  "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
  "source_column": "string",
  "column_property_map": null,
  "column_descriptions": null,
  "key_column": "string",
  "is_enabled": true,
  "consecutive_failures": 0,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "last_sync_error": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "sync_frequency_interval_seconds": 0,
  "next_sync_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "job_id": "string",
    "account_segment": "tracked",
    "sync_phase": "staging",
    "attempt": 0,
    "workflow_id": "string",
    "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952",
    "temporal_url": "http://example.com",
    "trigger": "string",
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "rows_read": 0,
    "changed": 0,
    "existing": 0,
    "produced": 0,
    "skipped_missing_person": 0,
    "error": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "external_data_source": "8df47340-930c-47e2-b1d9-b1b8d55c351d",
  "table_name": "string",
  "saved_query_name": "string"
}

Update custom property sources

Required API key scopes

account:write

Path parameters

id
string

Request parameters

source_column
string
key_column
string
column_property_map
column_descriptions
is_enabled
boolean

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "definition": "c35d856b-b1ee-4229-bde7-cabd2df03b58",
  "saved_query": "e3652b9e-1a82-4fa6-9330-52b013787fcc",
  "external_data_schema": "ba92a32d-bbb9-4eb7-b909-202e1efb6c98",
  "source_column": "string",
  "column_property_map": null,
  "column_descriptions": null,
  "key_column": "string",
  "is_enabled": true,
  "consecutive_failures": 0,
  "last_synced_at": "2019-08-24T14:15:22Z",
  "last_sync_error": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "sync_frequency_interval_seconds": 0,
  "next_sync_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "job_id": "string",
    "account_segment": "tracked",
    "sync_phase": "staging",
    "attempt": 0,
    "workflow_id": "string",
    "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952",
    "temporal_url": "http://example.com",
    "trigger": "string",
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "rows_read": 0,
    "changed": 0,
    "existing": 0,
    "produced": 0,
    "skipped_missing_person": 0,
    "error": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "external_data_source": "8df47340-930c-47e2-b1d9-b1b8d55c351d",
  "table_name": "string",
  "saved_query_name": "string"
}

Delete custom property sources

Required API key scopes

account:write

Path parameters

id
string

Example request

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

Example response

Status 204 No response body

Create custom property sources

Person and group sources only: start a backfill that reads the whole warehouse table and populates person or group properties for historical rows. If one is already running for the table, queue a follow-up that observes the latest mapping.

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/custom_property_sources/:id/backfill
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/custom_property_sources/:id/backfill/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/custom_property_sources/{custom_property_source_id}/backfill/".format(
        project_id=project_id,
		custom_property_source_id="<the custom property source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 202

RESPONSE
{
  "status": "triggered",
  "already_running": true
}

List all custom property sources runs

The source's sync history, newest first. Person and group runs require viewer access to their warehouse source because the response includes row counts and sync errors.

Path parameters

id
string

Query parameters

limit
integer
offset
integer
search
string

Response

Example request

GET /api/projects/:project_id/custom_property_sources/:id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/custom_property_sources/:id/runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/custom_property_sources/{custom_property_source_id}/runs/".format(
        project_id=project_id,
		custom_property_source_id="<the custom property source 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",
      "job_id": "string",
      "account_segment": "tracked",
      "sync_phase": "staging",
      "attempt": 0,
      "workflow_id": "string",
      "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952",
      "temporal_url": "http://example.com",
      "trigger": "string",
      "status": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "rows_read": 0,
      "changed": 0,
      "existing": 0,
      "produced": 0,
      "skipped_missing_person": 0,
      "error": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create custom property sources

Person and group sources only: run what this source reads now — an import for a table binding (a real, billable warehouse sync), a materialization for a view binding. The incremental person/group-property update runs off that run.

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/custom_property_sources/:id/sync
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/custom_property_sources/:id/sync/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/custom_property_sources/{custom_property_source_id}/sync/".format(
        project_id=project_id,
		custom_property_source_id="<the custom property source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 202

RESPONSE
{
  "status": "triggered",
  "already_running": true
}