> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evermuse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# /ingest/batches

> Returns a paginated list of batches you've submitted, newest first.

Use the `nextCursor` value from the response as the `cursor` query parameter to fetch the next page.




## OpenAPI

````yaml /openapi/ingest-v1.yaml get /api/v1/ingest/batches
openapi: 3.1.0
info:
  title: Evermuse API
  version: 1.0.0
  description: >
    The Evermuse API lets you send your data into Evermuse for analysis.

    Each record describes *what* happened and *when*, then you send it as JSON
    or newline-delimited JSON (NDJSON).


    ## Quick start


    1. Create an API key in **Settings > API Keys** with the `api:write`
    permission.

    2. `POST /api/v1/ingest` with your records (see examples below).

    3. Check `GET /api/v1/ingest/batches/{batchId}` to track progress.


    ## Authentication


    Every request must include an `x-api-key` header with your API key
    (`em_sk_...`).


    ## Content types


    | Content-Type | Use case |

    |---|---|

    | `application/json` | Array of records, or `{ "records": [...] }` wrapper |

    | `application/x-ndjson` | High-volume sends — one JSON object per line |


    ## Batching


    All records in a single request must share the same `_type` and
    `_product_id`.

    A batch can contain up to 1,000 records.
servers:
  - url: https://api.evermuse.com
    description: Evermuse API
security: []
tags:
  - name: ingestion
    description: Send data to Evermuse
paths:
  /api/v1/ingest/batches:
    get:
      tags:
        - ingestion
      summary: /ingest/batches
      description: >
        Returns a paginated list of batches you've submitted, newest first.


        Use the `nextCursor` value from the response as the `cursor` query
        parameter to fetch the next page.
      operationId: listBatches
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: |
            Number of batches to return per page. Defaults to 20, maximum 100.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            maxLength: 256
          description: |
            Pagination cursor from a previous response's `nextCursor` field.
            Omit to start from the most recent batch.
      responses:
        '200':
          description: A page of batches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestBatchListResponse'
        '401':
          description: Unauthorized. The `x-api-key` header is missing or invalid.
        '403':
          description: Forbidden. The API key does not have the required permission.
        '500':
          description: Internal server error. Please retry the request.
      security:
        - IngestApiKey: []
components:
  schemas:
    IngestBatchListResponse:
      type: object
      additionalProperties: false
      required:
        - batches
        - nextCursor
      properties:
        batches:
          type: array
          description: List of batches, ordered by creation time (newest first).
          items:
            $ref: '#/components/schemas/IngestBatchStatus'
        nextCursor:
          type: string
          nullable: true
          maxLength: 256
          description: >
            Pass this value as the `cursor` query parameter to fetch the next
            page.

            `null` when there are no more results.
    IngestBatchStatus:
      type: object
      additionalProperties: false
      required:
        - batchId
        - status
        - acceptedCount
        - rejectedCount
        - totalErrorCount
        - createdAt
      properties:
        batchId:
          type: string
          maxLength: 128
          description: Unique identifier for this batch.
        status:
          type: string
          enum:
            - LANDING
            - LANDED
            - PROCESSING
            - COMPLETE
            - FAILED
          description: |
            Current processing status of the batch.
            See the batch lifecycle table in the endpoint description.
        createdAt:
          type: number
          description: When the batch was created, as Unix epoch milliseconds.
          example: 1709282096000
        acceptedCount:
          type: integer
          minimum: 0
          description: Number of records that passed validation.
        rejectedCount:
          type: integer
          minimum: 0
          description: Number of records that failed validation.
        totalErrorCount:
          type: integer
          minimum: 0
          description: Total number of validation errors across rejected records.
        errors:
          type: array
          description: Up to 20 validation errors for quick inspection.
          maxItems: 20
          items:
            $ref: '#/components/schemas/IngestRecordError'
        source:
          type: string
          description: Where the records in this batch came from.
        type:
          type: string
          description: The record type for this batch.
        attachmentDownloadTotal:
          type: integer
          minimum: 0
          description: >-
            Total number of attachments to be downloaded (shown when the batch
            includes file attachments).
        attachmentDownloadComplete:
          type: integer
          minimum: 0
          description: Number of attachments successfully downloaded.
        attachmentDownloadFailed:
          type: integer
          minimum: 0
          description: Number of attachments that failed to download.
        attachmentDownloadStatus:
          type: string
          enum:
            - PENDING
            - IN_PROGRESS
            - COMPLETE
            - PARTIAL_FAILURE
            - FAILED
          description: |
            Overall download status for the batch's attachments.
            Only shown when the batch includes file attachments.
    IngestRecordError:
      type: object
      additionalProperties: false
      required:
        - index
        - code
        - message
      properties:
        index:
          type: integer
          minimum: 0
          description: Position of the rejected record in the submitted batch (0-based).
        code:
          type: string
          maxLength: 64
          description: Machine-readable error code (e.g., `VALIDATION_ERROR`).
        message:
          type: string
          maxLength: 2048
          description: Human-readable description of what went wrong.
  securitySchemes:
    IngestApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        Your API key, sent as the `x-api-key` header.
        Create one in **Settings > API Keys** with `api:write` permission.
        Format: `em_sk_...`

````