Batch

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

Endpoints

    GET/api/projects/:project_id/batch_exports/:batch_export_id/runs/:id/
    POST/api/projects/:project_id/batch_exports/:batch_export_id/runs/:id/cancel/
    GET/api/projects/:project_id/batch_exports/:batch_export_id/runs/:id/logs/
    POST/api/projects/:project_id/batch_exports/:batch_export_id/runs/:id/retry/
    GET/api/projects/:project_id/batch_exports/:id/
    PATCH/api/projects/:project_id/batch_exports/:id/
    DELETE/api/projects/:project_id/batch_exports/:id/
    POST/api/projects/:project_id/batch_exports/:id/backfill/
    GET/api/projects/:project_id/batch_exports/:id/logs/
    POST/api/projects/:project_id/batch_exports/:id/pause/
    POST/api/projects/:project_id/batch_exports/:id/run_test_step/
    POST/api/projects/:project_id/batch_exports/:id/unpause/
    POST/api/projects/:project_id/batch_exports/run_test_step_new/
    GET/api/projects/:project_id/batch_exports/test/

    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


    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/

    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
      • 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.

    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"

    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/.

    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/

    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
      • 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.

    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"

    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


    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/

    Response

    Status 200
    RESPONSE
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "team_id": 0,
      "name": "string",
      "model": "events",
      "destination": {
        "type": "S3",
        "config": null
      },
      "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


    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"

    Response

    Status 200
    RESPONSE
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "team_id": 0,
      "name": "string",
      "model": "events",
      "destination": {
        "type": "S3",
        "config": null
      },
      "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/.

    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/

    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

    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

    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/.

    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/

    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

    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

    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

    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

    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

    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

    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

    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

    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/.

    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/

    Response

    Status 200 No response body

    Community questions

    Was this page useful?