---
title: "List form submissions, newest first"
method: GET
path: "/api/v1/sites/{slug}/form-submissions"
tags: ["Forms"]
---

# List form submissions, newest first

`GET /api/v1/sites/{slug}/form-submissions`

## Request

- Base URL: `https://api.dotsy.ai`
- URL: `https://api.dotsy.ai/api/v1/sites/{slug}/form-submissions`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Returns submissions newest first, a page at a time. Pass `form` to scope to one form; omit it to list every form together. Narrow the list with `fromMs` and `toMs` (a time range) or `q` (email or any field value, case-insensitive).

Each item carries the full `fields`, so treat the response as personal data. To page, send `nextCursor` back as `cursor` until it comes back `null`. Submissions hold visitors' personal data, so this needs at least the `editor` role on the site. A `viewer` gets `403` `forbidden_role`.

## Path parameters

- `slug` string, required

## Query parameters

- `form` string
- `limit` integer
- `cursor` string
- `fromMs` integer
- `toMs` integer
- `q` string

## Response `200`

One page of submissions.

- FormSubmissionList
  - `items` FormSubmission[], required
    - `id` string, required: Submission id.
    - `formId` string, required: The form this was submitted through.
    - `pagePath` string, nullable, required: Path of the page the visitor submitted from, when known.
    - `fields` object, required: What the visitor filled in: field name to value. Personal data lives here.
    - `replyTo` string, nullable, required: The visitor's email address, when the form has one. Use it to search.
    - `meta` object, nullable, required: Extra facts about the submission, such as a hash of the visitor's IP address (`ip_hash`).
    - `sizeBytes` integer, required: Size of the stored submission in bytes.
    - `createdAt` integer, required: When it was submitted, Unix ms.
  - `nextCursor` string, nullable, required: Pass as `cursor` (with the same `limit`) for the next page; null on the last page.
  - `formId` string: The form that was listed. Omitted when `form` was not passed (all forms, newest first).

## Other responses

- `401`: Missing or invalid credentials.
- `403`: The caller's role can't read submissions (`forbidden_role`), or the site's storage can't hold them (`backend_required`, which has `code` and `message` instead of `error`).
- `404`: No such site, or it is not visible to this account.

---

[API](https://skmtc.dev/dotsy/apis/dotsy-api.md) · [All operations](https://skmtc.dev/dotsy/apis/dotsy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dotsy/apis/dotsy-api/revisions/4272ed3b85d7?raw)