Batch

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

Endpoints

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

Retrieve batch exports runs

Required API key scopes

batch_export:read

Path parameters

  • batch_export_id
    string

    The BatchExport this run belongs to.

  • id
    string

    A UUID string identifying this batch export run.

  • 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/projects/:project_id/batch_exports/:batch_export_id/runs/: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/batch_exports/:batch_export_id/runs/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "Cancelled",
  "records_completed": -2147483648,
  "latest_error": "string",
  "data_interval_start": "2019-08-24T14:15:22Z",
  "data_interval_end": "2019-08-24T14:15:22Z",
  "cursor": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z",
  "last_updated_at": "2019-08-24T14:15:22Z",
  "records_total_count": -2147483648,
  "bytes_exported": -9223372036854776000,
  "batch_export": "0fa0a8a1-f280-4977-8bb4-bc7801a6902f",
  "backfill": "4f806519-f4aa-4807-bea5-95595ab1adf0"
}

Create batch exports runs cancel

Cancel a batch export run.

Required API key scopes

batch_export:write

Path parameters

  • batch_export_id
    string

    The BatchExport this run belongs to.

  • id
    string

    A UUID string identifying this batch export run.

  • 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

  • status

    The status of this run.

    • Cancelled - Cancelled
    • Completed - Completed
    • ContinuedAsNew - Continued As New
    • Failed - Failed
    • FailedRetryable - Failed Retryable
    • FailedBilling - Failed Billing
    • Terminated - Terminated
    • TimedOut - Timedout
    • Running - Running
    • Starting - Starting
  • records_completed
    integer

    The number of records that have been exported.

  • latest_error
    string

    The latest error that occurred during this run.

  • data_interval_start
    string

    The start of the data interval.

  • data_interval_end
    string

    The end of the data interval.

  • cursor
    string

    An opaque cursor that may be used to resume.

  • finished_at
    string

    The timestamp at which this BatchExportRun finished, successfully or not.

  • records_total_count
    integer

    The total count of records that should be exported in this BatchExportRun.

  • bytes_exported
    integer

    The number of bytes that have been exported in this BatchExportRun.

  • backfill
    string

    The backfill this run belongs to.

Example request

POST /api/projects/:project_id/batch_exports/:batch_export_id/runs/:id/cancel
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/batch_exports/:batch_export_id/runs/:id/cancel/\
	-d status=undefined,\
	-d data_interval_end="string"

Example response

Status 200 No response body

Retrieve batch exports runs logs

Path parameters

  • batch_export_id
    string

    The BatchExport this run belongs to.

  • id
    string

    A UUID string identifying this batch export run.

  • 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/projects/:project_id/batch_exports/:batch_export_id/runs/:id/logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/batch_exports/:batch_export_id/runs/:id/logs/

Example response

Status 200 No response body

Create batch exports runs retry

Retry a batch export run.

We use the same underlying mechanism as when backfilling a batch export, as retrying a run is the same as backfilling one run.

Required API key scopes

batch_export:write

Path parameters

  • batch_export_id
    string

    The BatchExport this run belongs to.

  • id
    string

    A UUID string identifying this batch export run.

  • 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

  • status

    The status of this run.

    • Cancelled - Cancelled
    • Completed - Completed
    • ContinuedAsNew - Continued As New
    • Failed - Failed
    • FailedRetryable - Failed Retryable
    • FailedBilling - Failed Billing
    • Terminated - Terminated
    • TimedOut - Timedout
    • Running - Running
    • Starting - Starting
  • records_completed
    integer

    The number of records that have been exported.

  • latest_error
    string

    The latest error that occurred during this run.

  • data_interval_start
    string

    The start of the data interval.

  • data_interval_end
    string

    The end of the data interval.

  • cursor
    string

    An opaque cursor that may be used to resume.

  • finished_at
    string

    The timestamp at which this BatchExportRun finished, successfully or not.

  • records_total_count
    integer

    The total count of records that should be exported in this BatchExportRun.

  • bytes_exported
    integer

    The number of bytes that have been exported in this BatchExportRun.

  • backfill
    string

    The backfill this run belongs to.

Example request

POST /api/projects/:project_id/batch_exports/:batch_export_id/runs/:id/retry
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/batch_exports/:batch_export_id/runs/:id/retry/\
	-d status=undefined,\
	-d data_interval_end="string"

Example response

Status 200 No response body

Retrieve batch exports retrieve

Required API key scopes

batch_export:read

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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/projects/:project_id/batch_exports/: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/batch_exports/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "name": "string",
  "model": "events",
  "destination": {
    "type": "S3",
    "config": null,
    "integration": 0,
    "integration_id": 0
  },
  "interval": "hour",
  "paused": true,
  "created_at": "2019-08-24T14:15:22Z",
  "last_updated_at": "2019-08-24T14:15:22Z",
  "last_paused_at": "2019-08-24T14:15:22Z",
  "start_at": "2019-08-24T14:15:22Z",
  "end_at": "2019-08-24T14:15:22Z",
  "latest_runs": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "status": "Cancelled",
      "records_completed": -2147483648,
      "latest_error": "string",
      "data_interval_start": "2019-08-24T14:15:22Z",
      "data_interval_end": "2019-08-24T14:15:22Z",
      "cursor": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "last_updated_at": "2019-08-24T14:15:22Z",
      "records_total_count": -2147483648,
      "bytes_exported": -9223372036854776000,
      "batch_export": "0fa0a8a1-f280-4977-8bb4-bc7801a6902f",
      "backfill": "4f806519-f4aa-4807-bea5-95595ab1adf0"
    }
  ],
  "hogql_query": "string",
  "schema": null,
  "filters": null
}

Update batch exports update

Required API key scopes

batch_export:write

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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

  • name
    string

    A human-readable name for this BatchExport.

  • model

    Which model this BatchExport is exporting.

    • events - Events
    • persons - Persons
    • sessions - Sessions
  • destination
  • interval
  • paused
    boolean

    Whether this BatchExport is paused or not.

  • last_paused_at
    string

    The timestamp at which this BatchExport was last paused.

  • start_at
    string

    Time before which any Batch Export runs won't be triggered.

  • end_at
    string

    Time after which any Batch Export runs won't be triggered.

  • hogql_query
    string
  • filters

Response


Example request

PATCH /api/projects/:project_id/batch_exports/: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/batch_exports/:id/\
	-d team_id="integer"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "name": "string",
  "model": "events",
  "destination": {
    "type": "S3",
    "config": null,
    "integration": 0,
    "integration_id": 0
  },
  "interval": "hour",
  "paused": true,
  "created_at": "2019-08-24T14:15:22Z",
  "last_updated_at": "2019-08-24T14:15:22Z",
  "last_paused_at": "2019-08-24T14:15:22Z",
  "start_at": "2019-08-24T14:15:22Z",
  "end_at": "2019-08-24T14:15:22Z",
  "latest_runs": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "status": "Cancelled",
      "records_completed": -2147483648,
      "latest_error": "string",
      "data_interval_start": "2019-08-24T14:15:22Z",
      "data_interval_end": "2019-08-24T14:15:22Z",
      "cursor": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "last_updated_at": "2019-08-24T14:15:22Z",
      "records_total_count": -2147483648,
      "bytes_exported": -9223372036854776000,
      "batch_export": "0fa0a8a1-f280-4977-8bb4-bc7801a6902f",
      "backfill": "4f806519-f4aa-4807-bea5-95595ab1adf0"
    }
  ],
  "hogql_query": "string",
  "schema": null,
  "filters": null
}

Delete batch exports destroy

Required API key scopes

batch_export:write

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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/projects/:project_id/batch_exports/: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/batch_exports/:id/

Example response

Status 204 No response body

Create batch exports backfill create

Trigger a backfill for a BatchExport.

Note: This endpoint is deprecated. Please use POST /batch_exports/<id>/backfills/ instead.

Required API key scopes

batch_export:write

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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

  • name
    string

    A human-readable name for this BatchExport.

  • model

    Which model this BatchExport is exporting.

    • events - Events
    • persons - Persons
    • sessions - Sessions
  • destination
  • interval
  • paused
    boolean

    Whether this BatchExport is paused or not.

  • last_paused_at
    string

    The timestamp at which this BatchExport was last paused.

  • start_at
    string

    Time before which any Batch Export runs won't be triggered.

  • end_at
    string

    Time after which any Batch Export runs won't be triggered.

  • hogql_query
    string
  • filters

Example request

POST /api/projects/:project_id/batch_exports/: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/batch_exports/:id/backfill/\
	-d name="string",\
	-d destination=undefined,\
	-d interval=undefined

Example response

Status 200 No response body

Retrieve batch exports logs retrieve

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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/projects/:project_id/batch_exports/:id/logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/batch_exports/:id/logs/

Example response

Status 200 No response body

Create batch exports pause create

Pause a BatchExport.

Required API key scopes

batch_export:write

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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

  • name
    string

    A human-readable name for this BatchExport.

  • model

    Which model this BatchExport is exporting.

    • events - Events
    • persons - Persons
    • sessions - Sessions
  • destination
  • interval
  • paused
    boolean

    Whether this BatchExport is paused or not.

  • last_paused_at
    string

    The timestamp at which this BatchExport was last paused.

  • start_at
    string

    Time before which any Batch Export runs won't be triggered.

  • end_at
    string

    Time after which any Batch Export runs won't be triggered.

  • hogql_query
    string
  • filters

Example request

POST /api/projects/:project_id/batch_exports/:id/pause
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/batch_exports/:id/pause/\
	-d name="string",\
	-d destination=undefined,\
	-d interval=undefined

Example response

Status 200 No response body

Create batch exports run test step create

Required API key scopes

INTERNAL

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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

  • name
    string

    A human-readable name for this BatchExport.

  • model

    Which model this BatchExport is exporting.

    • events - Events
    • persons - Persons
    • sessions - Sessions
  • destination
  • interval
  • paused
    boolean

    Whether this BatchExport is paused or not.

  • last_paused_at
    string

    The timestamp at which this BatchExport was last paused.

  • start_at
    string

    Time before which any Batch Export runs won't be triggered.

  • end_at
    string

    Time after which any Batch Export runs won't be triggered.

  • hogql_query
    string
  • filters

Example request

POST /api/projects/:project_id/batch_exports/:id/run_test_step
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/batch_exports/:id/run_test_step/\
	-d name="string",\
	-d destination=undefined,\
	-d interval=undefined

Example response

Status 200 No response body

Create batch exports unpause create

Unpause a BatchExport.

Required API key scopes

batch_export:write

Path parameters

  • id
    string

    A UUID string identifying this batch export.

  • 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

  • name
    string

    A human-readable name for this BatchExport.

  • model

    Which model this BatchExport is exporting.

    • events - Events
    • persons - Persons
    • sessions - Sessions
  • destination
  • interval
  • paused
    boolean

    Whether this BatchExport is paused or not.

  • last_paused_at
    string

    The timestamp at which this BatchExport was last paused.

  • start_at
    string

    Time before which any Batch Export runs won't be triggered.

  • end_at
    string

    Time after which any Batch Export runs won't be triggered.

  • hogql_query
    string
  • filters

Example request

POST /api/projects/:project_id/batch_exports/:id/unpause
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/batch_exports/:id/unpause/\
	-d name="string",\
	-d destination=undefined,\
	-d interval=undefined

Example response

Status 200 No response body

Create batch exports run test step new create

Required API key scopes

INTERNAL

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

  • name
    string

    A human-readable name for this BatchExport.

  • model

    Which model this BatchExport is exporting.

    • events - Events
    • persons - Persons
    • sessions - Sessions
  • destination
  • interval
  • paused
    boolean

    Whether this BatchExport is paused or not.

  • last_paused_at
    string

    The timestamp at which this BatchExport was last paused.

  • start_at
    string

    Time before which any Batch Export runs won't be triggered.

  • end_at
    string

    Time after which any Batch Export runs won't be triggered.

  • hogql_query
    string
  • filters

Example request

POST /api/projects/:project_id/batch_exports/run_test_step_new
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/batch_exports/run_test_step_new/\
	-d name="string",\
	-d destination=undefined,\
	-d interval=undefined

Example response

Status 200 No response body

Retrieve batch exports test retrieve

Required API key scopes

INTERNAL

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

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

Example response

Status 200 No response body

Community questions

Questions about this page? or post a community question.