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

# list_submissions

> MCP tool - read a form's submissions from an agent. Metadata by default; content is opt-in.

<Info>**Free** - like the rest of the MCP server, `list_submissions` is not plan-gated.</Info>

Lets an agent check a form's inbox or quarantine without opening the dashboard —
useful for a prompt like "did anyone submit the contact form today?" By default this
returns **metadata only**; the visitor's message body and any submitted email address
are withheld unless you explicitly ask for them.

## Input schema

| Field            | Type                | Required | Notes                                                                            |
| ---------------- | ------------------- | -------- | -------------------------------------------------------------------------------- |
| `formId`         | `string`            | yes      | The form to read (`frm_…`), owner-scoped.                                        |
| `folder`         | `"inbox" \| "spam"` | no       | Defaults to `inbox`. `spam` reads the [quarantine](/docs/features/quarantine) folder. |
| `limit`          | `number`            | no       | Defaults to 20; clamped to the range 1–100.                                      |
| `includeContent` | `boolean`           | no       | Defaults to `false`. See PII note below.                                         |

## Example call

```json theme={null}
{
  "name": "list_submissions",
  "arguments": {
    "formId": "frm_...",
    "folder": "inbox",
    "limit": 10
  }
}
```

## Returned shape (default - metadata only)

```json theme={null}
{
  "counts": { "inbox": 42, "spam": 3 },
  "submissions": [
    { "id": "sub_...", "created_at": 1720700000000, "folder": "inbox", "status": "delivered" }
  ]
}
```

| Field                          | Type     | Meaning                                                                |
| ------------------------------ | -------- | ---------------------------------------------------------------------- |
| `counts.inbox` / `counts.spam` | `number` | Total submissions in each folder for this form, regardless of `limit`. |
| `submissions[].id`             | `string` | Submission id (`sub_…`).                                               |
| `submissions[].created_at`     | `number` | Unix epoch **milliseconds**.                                           |
| `submissions[].folder`         | `string` | Echoes the requested `folder`.                                         |
| `submissions[].status`         | `string` | The submission's delivery status.                                      |
| `submissions[].data`           | `object` | **Only present when `includeContent: true`** - see below.              |

## Metadata-only by default: the PII posture

Form submissions routinely contain a visitor's name, email address, and free-text
message - that's third-party personal data, not the form owner's own. `list_submissions`
treats that as sensitive by default: unless you pass `includeContent: true`, the
`data` field is omitted entirely from every submission in the response, and only
`id` / `created_at` / `folder` / `status` come back.

Set `includeContent: true` to get the submitted fields:

```json theme={null}
{
  "name": "list_submissions",
  "arguments": { "formId": "frm_...", "includeContent": true }
}
```

```json theme={null}
{
  "counts": { "inbox": 42, "spam": 3 },
  "submissions": [
    {
      "id": "sub_...",
      "created_at": 1720700000000,
      "folder": "inbox",
      "status": "delivered",
      "data": { "name": "John Smith", "email": "john@example.com", "message": "Hello!" }
    }
  ]
}
```

<Note>
  Only opt into `includeContent` when the task actually needs the message text or
  visitor's email - e.g. summarizing recent feedback. For a presence/count check
  ("has anyone submitted today?"), the default metadata-only response is enough and
  keeps visitor content out of the agent's context.
</Note>

## Errors

A `formId` that doesn't exist, or isn't owned by the account behind the token, returns:

```
not_found: no form with that id on your account
```

An invalid or revoked token returns the same auth error as every MCP tool - see
[MCP server](/docs/agents/mcp-server#auth).

<CardGroup cols={2}>
  <Card title="Quarantine" icon="box-archive" href="/docs/features/quarantine">
    What lands in the spam folder, and why.
  </Card>

  <Card title="create_form" icon="wand-magic-sparkles" href="/docs/agents/create-form">
    Where the formId you'd pass here comes from.
  </Card>
</CardGroup>