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

# Upload one chunk of records

> Stages one chunk of records against an open record set. Chunks may be sent in any order. Re-sending a chunk index that has already been received is safe: the response reports `replay: true` and the record set's counters do not move.



## OpenAPI

````yaml /openapi.json post /record-sets/{record_set_id}/records
openapi: 3.1.0
info:
  title: GetDialed Flows API
  version: 0.1.0
servers:
  - url: https://api.getdialed.ai/flows
    description: Production
security: []
paths:
  /record-sets/{record_set_id}/records:
    post:
      tags:
        - record-sets
      summary: Upload one chunk of records
      description: >-
        Stages one chunk of records against an open record set. Chunks may be
        sent in any order. Re-sending a chunk index that has already been
        received is safe: the response reports `replay: true` and the record
        set's counters do not move.
      operationId: append_records_record_sets__record_set_id__records_post
      parameters:
        - name: record_set_id
          in: path
          required: true
          schema:
            type: string
            title: Record Set Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordSetChunkCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordSetChunkResponse'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              example:
                detail: Authentication required
        '403':
          description: Admin role required
          content:
            application/json:
              example:
                detail: Admin role required
        '404':
          description: Not found — also returned on cross-tenant access (never 403)
          content:
            application/json:
              example:
                detail: Record set not found
        '409':
          description: Conflict — the record set's state does not allow this request
          content:
            application/json:
              example:
                detail: Record set is not open
        '413':
          description: Request body too large — split the upload into more chunks
          content:
            application/json:
              example:
                detail: Request body exceeds 16777216 bytes
        '422':
          description: Validation error (see body for field details)
          content:
            application/json:
              example:
                detail: Validation error
        '429':
          description: Rate limit exceeded — retry after the Retry-After header
          content:
            application/json:
              example:
                detail: Rate limit exceeded
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    RecordSetChunkCreate:
      properties:
        chunk_index:
          type: integer
          minimum: 0
          title: Chunk Index
          description: Zero-based index of this chunk within the record set.
        records:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Records
          description: >-
            The chunk's records, in dial order. At most `chunk_size` of them,
            and each one below the per-record size limit.
      type: object
      required:
        - chunk_index
        - records
      title: RecordSetChunkCreate
      description: >-
        One chunk of records for an open record set.


        `chunk_index` is assigned by you, starting at 0, and is what makes the

        upload safe to retry: re-sending the same `chunk_index` with the same

        records is recognised as a repeat and inserts nothing, so a network
        failure

        mid-upload is resolved by simply sending the chunk again. The response
        tells

        you whether the chunk was new (`replay: false`) or already had been
        received

        (`replay: true`).


        A row's position in the record set is `chunk_index * chunk_size +
        offset`,

        where `offset` is the record's position within this chunk. A short chunk
        in

        the middle of the upload therefore leaves a gap in the numbering, which
        is

        harmless: rows are processed by range and sealing validates the totals.
        If

        you would rather have no gaps, send full chunks and make the last one
        short.


        Chunks may be sent in any order, and out-of-order or retried chunks do
        not

        change the record set's content hash.
      example:
        chunk_index: 0
        records:
          - name: Placeholder One
            phone: '+15555550100'
          - name: Placeholder Two
            phone: '+15555550101'
    RecordSetChunkResponse:
      properties:
        record_set_id:
          type: string
          title: Record Set Id
        chunk_index:
          type: integer
          title: Chunk Index
        records_received:
          type: integer
          title: Records Received
        inserted:
          type: integer
          title: Inserted
        replay:
          type: boolean
          title: Replay
        received_count:
          type: integer
          title: Received Count
      type: object
      required:
        - record_set_id
        - chunk_index
        - records_received
        - inserted
        - replay
        - received_count
      title: RecordSetChunkResponse
      description: >-
        The outcome of one chunk upload.


        `records_received` is how many records the chunk carried and `inserted`
        is

        how many of them were new. `replay` is true when this chunk index had

        already been received, in which case `inserted` is normally 0 and the
        record

        set's counters are unchanged. `received_count` is the record set's
        running

        total after this chunk, which is the number to pass as `expected_count`
        when

        every chunk has been sent.
      example:
        chunk_index: 0
        inserted: 10000
        received_count: 10000
        record_set_id: rs_0123456789abcdef
        records_received: 10000
        replay: false
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````