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

# List submissions

> Retrieve a paginated list of submissions. Optionally filter by a specific form using `formId`.



## OpenAPI

````yaml /openapi.json get /submissions
openapi: 3.1.0
info:
  title: PipedForm API
  description: >-
    PipedForm is a form-to-integration platform that lets you capture form
    submissions and route them anywhere — email, Google Sheets, Slack, Notion,
    and more — without setting up or maintaining a backend.


    This API allows you to programmatically retrieve your forms and submissions.
  version: 1.0.0
  contact:
    name: PipedForm Support
    url: https://pipedform.com
servers:
  - url: https://pipedform.com/api/v1
security:
  - BearerAuth: []
tags:
  - name: Forms
    description: Endpoints for retrieving your forms
  - name: Submissions
    description: Endpoints for retrieving form submissions
paths:
  /submissions:
    get:
      tags:
        - Submissions
      summary: List submissions
      description: >-
        Retrieve a paginated list of submissions. Optionally filter by a
        specific form using `formId`.
      operationId: listSubmissions
      parameters:
        - name: formId
          in: query
          required: false
          description: Only return submissions belonging to this form.
          schema:
            type: string
            format: uuidv7
            examples:
              - 019f40ed-65aa-754b-90dd-504b87836506
        - name: limit
          in: query
          required: false
          description: Maximum number of submissions to return.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          description: >-
            Cursor for pagination. Pass the `nextCursor` value from a previous
            response to fetch the next page.
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of submissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    SubmissionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Submission'
        nextCursor:
          type: string
          description: >-
            Cursor to retrieve the next page of results. `null` if there are no
            more results.
          examples:
            - eyJpZCI6IjAxOWY0MGVkIn0=
      required:
        - data
    Submission:
      type: object
      properties:
        id:
          type: string
          format: uuidv7
          examples:
            - 019f40ed-2046-7985-9628-8ff55ce6a67c
        formId:
          type: string
          format: uuidv7
          examples:
            - 019f40ed-65aa-754b-90dd-504b87836506
        fields:
          type: object
          description: >-
            The submitted form data, keyed by field name. Values may be strings,
            arrays, nested objects, or file attachments.
          additionalProperties: true
          examples:
            - name: John
              email: john@gmail.com
              message: This is a message from John.
        ipAddress:
          type:
            - string
            - 'null'
          examples:
            - 127.0.0.1
        userAgent:
          type:
            - string
            - 'null'
          examples:
            - >-
              Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
              (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36
        submittedAt:
          type: string
          format: date-time
          examples:
            - '2026-07-08T10:00:00.000Z'
      required:
        - id
        - formId
        - fields
        - submittedAt
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - UNAUTHORIZED
                - NOT_FOUND
                - RATE_LIMIT_EXCEEDED
              examples:
                - UNAUTHORIZED
            message:
              type: string
              examples:
                - Invalid API key
          required:
            - code
            - message
      required:
        - error
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests. You have exceeded the rate limit for this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
            properties:
              error:
                properties:
                  code:
                    type: string
                    examples:
                      - RATE_LIMIT_EXCEEDED
                  message:
                    type: string
                    examples:
                      - Too many requests, please try againt later.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Provide your PipedForm API key as a Bearer token, e.g. `Authorization:
        Bearer YOUR_API_KEY`.

````