openapi: 3.2.0
info:
  title: Analytics Batch Exports API
  version: 1.0.0
  description: To acquire a personal access token go to [Account settings](https://analytics.pypestream.com/me/settings) and create a new token or use an existing one
servers:
- url: https://analytics.pypestream.com/
  description: Production server US
security:
- APIKey: []
tags:
- name: Batch Exports
paths:
  /api/datasets/{dataset_id}/batch_exports/:
    get:
      operationId: batch_exports_list
      description: Retrieves a paginated list of all batch export configurations for the specified dataset. Use this to view all active and inactive exports, their destinations, and schedules.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - Batch Exports
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBatchExportList'
          description: ''
    post:
      operationId: batch_exports_create
      description: "Creates a new batch export configuration. This endpoint requires a destination type (e.g., S3, Snowflake), an interval (e.g., daily, hourly), and the necessary credentials to configure the export pipeline.\n\n**Recommended Snowflake DDL:**\n```sql\nCREATE TABLE your_table_name (\n    uuid VARCHAR(36),\n    timestamp TIMESTAMP_NTZ,\n    created_at TIMESTAMP_NTZ,\n    event VARCHAR,\n    properties VARIANT,\n    distinct_id VARCHAR(36),\n    person_id VARCHAR(36),\n    person_properties VARIANT,\n    elements_chain VARCHAR\n);\n```\n\n**Beta notice:**\n  \nSnowflake support is currently in beta.\n"
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      tags:
      - Batch Exports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchExport'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchExport'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BatchExport'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExport'
          description: ''
  /api/datasets/{dataset_id}/batch_exports/{parent_lookup_batch_export_id}/runs/:
    get:
      operationId: batch_exports_runs_list
      description: Retrieves the execution history for a specific batch export. This returns a list of past runs, allowing you to monitor the success or failure status of the export schedule.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - in: path
        name: parent_lookup_batch_export_id
        schema:
          type: string
        required: true
      tags:
      - Batch Exports
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBatchExportRunList'
          description: ''
  /api/datasets/{dataset_id}/batch_exports/{parent_lookup_batch_export_id}/runs/{id}/:
    get:
      operationId: batch_exports_runs_retrieve
      description: Retrieves the details of a single execution run. This is useful for debugging specific failures or verifying the timestamps and data volume of a particular export cycle.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export run.
        required: true
      - in: path
        name: parent_lookup_batch_export_id
        schema:
          type: string
        required: true
      tags:
      - Batch Exports
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExportRun'
          description: ''
  /api/datasets/{dataset_id}/batch_exports/{id}/:
    get:
      operationId: batch_exports_retrieve
      description: Retrieves the full configuration details of a specific batch export identified by its ID.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export.
        required: true
      tags:
      - Batch Exports
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExport'
          description: ''
    put:
      operationId: batch_exports_update
      description: Updates an existing batch export configuration. This is a full update that replaces the current configuration with the data provided in the request body.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export.
        required: true
      tags:
      - Batch Exports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchExport'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchExport'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BatchExport'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExport'
          description: ''
    patch:
      operationId: batch_exports_partial_update
      description: Partially updates an existing batch export configuration. Use this to modify specific fields (such as the interval or destination settings) without replacing the entire object.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export.
        required: true
      tags:
      - Batch Exports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedBatchExport'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedBatchExport'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedBatchExport'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExport'
          description: ''
    delete:
      operationId: batch_exports_destroy
      description: Permanently deletes a batch export configuration. This action stops all future runs and removes the export setup from the project.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export.
        required: true
      tags:
      - Batch Exports
      responses:
        '204':
          description: No response body
  /api/datasets/{dataset_id}/batch_exports/{id}/backfill/:
    post:
      operationId: batch_exports_backfill_create
      description: 'Manually triggers a backfill job for a specific historical date range. This allows you to export data that was collected before the batch export was originally created or during a period where the export was paused.

        '
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export.
        required: true
      tags:
      - Batch Exports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchExportBackfill'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchExportBackfill'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BatchExportBackfill'
        required: true
      responses:
        '200':
          description: ''
  /api/datasets/{dataset_id}/batch_exports/{id}/pause/:
    post:
      operationId: batch_exports_pause_create
      description: Pauses the batch export schedule. New runs will not be triggered until the export is unpaused, but the configuration remains saved.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export.
        required: true
      tags:
      - Batch Exports
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExportPauseUnpauseResponse'
          description: ''
  /api/datasets/{dataset_id}/batch_exports/{id}/unpause/:
    post:
      operationId: batch_exports_unpause_create
      description: Resumes a paused batch export. The schedule will restart based on the configured interval.
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this batch export.
        required: true
      tags:
      - Batch Exports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchExportUnpause'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchExportUnpause'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BatchExportUnpause'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExportPauseUnpauseResponse'
          description: ''
components:
  schemas:
    PaginatedBatchExportRunList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchExportRun'
    BatchExportUnpause:
      type: object
      properties:
        backfill:
          type: boolean
          description: Whether to backfill the export for the period it was paused.
          default: false
    BatchExportDestination:
      type: object
      description: Serializer for an BatchExportDestination model.
      properties:
        type:
          enum:
          - S3
          - Snowflake
          type: string
          description: A choice of supported BatchExportDestination types.
        config:
          description: Configuration parameters for the destination. Shape depends on `type`.
          oneOf:
          - $ref: '#/components/schemas/S3BatchExportConfig'
          - $ref: '#/components/schemas/SnowflakeBatchExportConfig'
      required:
      - type
    BatchExportBackfill:
      type: object
      properties:
        start_at:
          type: string
          format: date-time
          description: The start date and time for the backfill in ISO format.
        end_at:
          type: string
          format: date-time
          description: The end date and time for the backfill in ISO format.
      required:
      - start_at
      - end_at
    BatchExportPauseUnpauseResponse:
      type: object
      properties:
        paused:
          type: boolean
          description: Whether the batch export is now paused.
    BatchExportRun:
      type: object
      description: Serializer for a BatchExportRun model.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        status:
          enum:
          - Cancelled
          - Completed
          - ContinuedAsNew
          - Failed
          - Terminated
          - TimedOut
          - Running
          - Starting
          type: string
          description: The status of this run.
        records_completed:
          type:
          - integer
          - 'null'
          maximum: 2147483647
          minimum: -2147483648
          description: The number of records that have been exported.
        latest_error:
          type:
          - string
          - 'null'
          description: The latest error that occurred during this run.
        data_interval_start:
          type: string
          format: date-time
          description: The start of the data interval.
        data_interval_end:
          type: string
          format: date-time
          description: The end of the data interval.
        cursor:
          type:
          - string
          - 'null'
          description: An opaque cursor that may be used to resume.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: The timestamp at which this BatchExportRun was created.
        finished_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The timestamp at which this BatchExportRun finished, successfully or not.
        last_updated_at:
          type: string
          format: date-time
          readOnly: true
          description: The timestamp at which this BatchExportRun was last updated.
        batch_export:
          type: string
          format: uuid
          readOnly: true
          description: The BatchExport this run belongs to.
      required:
      - batch_export
      - created_at
      - data_interval_end
      - data_interval_start
      - id
      - last_updated_at
      - status
    PatchedBatchExport:
      type: object
      description: Serializer for a BatchExport model.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          description: A human-readable name for this BatchExport.
        destination:
          $ref: '#/components/schemas/BatchExportDestination'
        interval:
          enum:
          - hour
          - day
          type: string
          description: The interval at which to export data.
        paused:
          type: boolean
          readOnly: true
          description: Whether this BatchExport is paused or not.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: The timestamp at which this BatchExport was created.
        last_updated_at:
          type: string
          format: date-time
          readOnly: true
          description: The timestamp at which this BatchExport was last updated.
        last_paused_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The timestamp at which this BatchExport was last paused.
        start_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Time before which any Batch Export runs won't be triggered.
        end_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Time after which any Batch Export runs won't be triggered.
        trigger_immediately:
          type: boolean
          default: false
        mask_pii:
          type: boolean
          default: false
          description: If true, personally identifiable information is masked in the properties of exported events. A property is considered to contain PII if a retention period is set for it.
    BatchExport:
      type: object
      description: Serializer for a BatchExport model.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          description: A human-readable name for this BatchExport.
        destination:
          $ref: '#/components/schemas/BatchExportDestination'
        interval:
          enum:
          - hour
          - day
          type: string
          description: The interval at which to export data.
        paused:
          type: boolean
          readOnly: true
          description: Whether this BatchExport is paused or not.
        mask_pii:
          type: boolean
          default: false
          description: If true, personally identifiable information is masked in the properties of exported events. A property is considered to contain PII if a retention period is set for it.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: The timestamp at which this BatchExport was created.
        last_updated_at:
          type: string
          format: date-time
          readOnly: true
          description: The timestamp at which this BatchExport was last updated.
        last_paused_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The timestamp at which this BatchExport was last paused.
        start_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Time before which any Batch Export runs won't be triggered.
        end_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Time after which any Batch Export runs won't be triggered.
        trigger_immediately:
          type: boolean
          default: false
      required:
      - created_at
      - destination
      - id
      - last_updated_at
      - name
      - paused
    S3BatchExportConfig:
      type: object
      description: Configuration required to export batches to Amazon S3.
      properties:
        bucket_name:
          type: string
          description: Name of the S3 bucket to write to.
        region:
          type: string
          description: AWS region of the S3 bucket (e.g. us-east-1).
        prefix:
          type: string
          description: Key prefix within the bucket where exported files are written.
        batch_window_size:
          type: integer
          description: Size of the batching window in seconds.
        aws_access_key_id:
          type: string
          description: AWS access key ID used for authentication.
        aws_secret_access_key:
          type: string
          description: AWS secret access key used for authentication.
      required:
      - bucket_name
      - region
      - prefix
      - batch_window_size
      - aws_access_key_id
      - aws_secret_access_key
    SnowflakeBatchExportConfig:
      type: object
      description: Configuration required to export batches to Snowflake.
      properties:
        user:
          type: string
          description: Snowflake user name.
        password:
          type: string
          description: Snowflake user password.
        account:
          type: string
          description: Snowflake account identifier.
        database:
          type: string
          description: Target Snowflake database name.
        schema:
          type: string
          description: Target Snowflake schema name.
        warehouse:
          type: string
          description: Snowflake virtual warehouse to use.
        table_name:
          type: string
          description: Target table name within the database/schema.
      required:
      - user
      - password
      - account
      - database
      - schema
      - warehouse
      - table_name
    PaginatedBatchExportList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchExport'
  securitySchemes:
    APIKey:
      type: http
      scheme: bearer
x-tagGroups:
- name: All endpoints
  tags:
  - Actions
  - Annotations
  - Batch Exports
  - Change
  - Cohorts
  - Dashboards
  - Datasets
  - Domains
  - Event Definitions
  - Events
  - Funnel
  - Insights
  - KPIs
  - Members
  - Organization
  - Persons
  - Projects
  - Property Definitions
  - Query
  - Tags
  - Trend
  - Users
  - Warehouse Table