> ## Documentation Index > Fetch the complete documentation index at: https://formcarry.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search submissions across forms > Searches the 25 most recently active forms this key can read and returns the matches with the form each one came from. Takes the same filters as a form's own list. Matches come grouped by form, and the response carries `complete: false` when the search did not reach every form or every match; narrow it with form_ids, team_id or a date range. For one form, use its own list, which pages through everything with a cursor. ## OpenAPI ````yaml https://api.formcarry.com/docs-json get /v1/submissions openapi: 3.0.0 info: title: formcarry API description: >- Welcome to the formcarry API. Authenticate every request with an API key from your team's API page in the dashboard, sent as `Authorization: Bearer fc_live_...`. Requests and responses are JSON. Lists are paginated with a cursor: pass a response's `next_cursor` as `cursor` to get the next page, until `next_cursor` is null. Errors return a `code` you can act on and a `message` you can show. Every response includes an `X-Request-Id` header; quote it when you contact support. version: '1' contact: {} servers: - url: https://api.formcarry.com security: [] tags: - name: forms description: Your forms - name: submissions description: Submissions received by a form - name: me description: The key you are using - name: health description: Service status paths: /v1/submissions: get: tags: - submissions summary: Search submissions across forms description: >- Searches the 25 most recently active forms this key can read and returns the matches with the form each one came from. Takes the same filters as a form's own list. Matches come grouped by form, and the response carries `complete: false` when the search did not reach every form or every match; narrow it with form_ids, team_id or a date range. For one form, use its own list, which pages through everything with a cursor. operationId: SubmissionSearchController_search parameters: - name: status required: false in: query description: 'Which submissions to include: the inbox (default), spam, or both.' schema: default: inbox enum: - inbox - spam - all type: string - name: read required: false in: query description: >- Only submissions that have (true) or have not (false) been read in the dashboard. schema: enum: - 'true' - 'false' type: string - name: has_attachments required: false in: query description: Only submissions with (true) or without (false) uploaded files. schema: enum: - 'true' - 'false' type: string - name: created_after required: false in: query description: >- Only submissions created at or after this time (RFC 3339, or milliseconds since the epoch). example: '2026-01-01T00:00:00Z' schema: type: string - name: created_before required: false in: query description: >- Only submissions created before this time (RFC 3339, or milliseconds since the epoch). example: '2026-02-01T00:00:00Z' schema: type: string - name: country required: false in: query description: >- Only submissions sent from this country. Two-letter uppercase code. For several, separate them with commas. Max 20. example: DE,AT,CH schema: type: string - name: q required: false in: query description: >- Only submissions where any field contains this text, matched literally and without case. 2 to 512 characters. On some forms a field that only appeared in very old submissions may be missed, so name that field with a field filter. example: pricing schema: type: string - name: order required: false in: query description: Newest first (the default) or oldest first. schema: default: newest enum: - newest - oldest type: string - name: limit required: false in: query description: >- Matches to return in total across every form searched. This search has no pages. schema: minimum: 1 maximum: 100 default: 25 type: number - name: fields required: false in: query description: >- Only return these submitted fields, separated by commas. Everything else about the submission still comes back. example: email,name schema: type: string - name: team_id required: false in: query description: Search this team only. Defaults to every team the key covers. example: 64b000000000000000000001 schema: type: string - name: form_ids required: false in: query description: >- Search only these forms, separated by commas. Forms the key cannot read are left out whether or not you name them. Defaults to the 25 most recently active forms the key can read. example: AbC123xyz,DeF456uvw schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SubmissionSearchList' '400': description: A query parameter is wrong. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_parameter: summary: invalid_parameter value: error: type: invalid_request_error code: invalid_parameter message: This key or connection does not cover that team. param: team_id request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '401': description: The request carried no usable key or token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: missing_bearer: summary: missing_bearer value: error: type: authentication_error code: missing_bearer message: >- Send your key as "Authorization: Bearer fc_live_..." on every request. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a invalid_key: summary: invalid_key value: error: type: authentication_error code: invalid_key message: >- This API key or access token is unknown, revoked or expired. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a wrong_audience: summary: wrong_audience value: error: type: authentication_error code: wrong_audience message: >- This access token was issued for a different resource. Authorize again for this server. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '403': description: The key is valid but may not do this. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: insufficient_scope: summary: insufficient_scope value: error: type: permission_error code: insufficient_scope message: This key is missing the submissions:write scope. required: - submissions:write request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a form_access_restricted: summary: form_access_restricted value: error: type: permission_error code: form_access_restricted message: >- This key is restricted to specific forms and cannot create new ones. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a team_inactive: summary: team_inactive value: error: type: permission_error code: team_inactive message: The team that owns this key is not active. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a owner_unverified: summary: owner_unverified value: error: type: permission_error code: owner_unverified message: >- The team owner must verify their email address before the API can be used. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '429': description: Too many searches at once for this key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: scan_concurrency: summary: scan_concurrency value: error: type: rate_limit_error code: scan_concurrency message: >- At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a security: - api_key: [] components: schemas: SubmissionSearchList: type: object properties: data: description: Matches across the forms searched, each carrying its form_id. type: array items: $ref: '#/components/schemas/SubmissionResource' forms_searched: type: number example: 12 description: How many of forms_matched were read before the search stopped. forms_matched: type: number example: 14 description: >- Forms picked for the search: the ones the key can read that matched form_ids, at most 25. complete: type: boolean description: >- False when the search did not reach every form or every match. Narrow it with form_ids, a date range or team_id. required: - data - forms_searched - forms_matched - complete ErrorEnvelope: type: object properties: error: $ref: '#/components/schemas/ErrorBody' required: - error SubmissionResource: type: object properties: id: type: string example: 64c000000000000000000001 form_id: type: string example: AbC123xyz created_at: type: string example: '2026-01-15T10:00:00.000Z' spam: type: boolean read: type: boolean ip: type: string nullable: true description: The address the submission came from, or null when unknown. country: type: string nullable: true example: DE description: Two letter uppercase code from the address, or null when unknown. user_agent: type: string nullable: true description: The visitor's browser, as it announced itself, or null. referer: type: string nullable: true description: The page the form was on, as the browser reported it, or null. fields: type: array items: $ref: '#/components/schemas/SubmissionField' attachments: type: array items: $ref: '#/components/schemas/SubmissionAttachment' required: - id - form_id - created_at - spam - read - ip - country - user_agent - referer - fields - attachments ErrorBody: type: object properties: type: type: string enum: - authentication_error - permission_error - invalid_request_error - rate_limit_error - api_error example: invalid_request_error code: type: string example: invalid_parameter message: type: string example: limit must not be greater than 100 param: type: string description: The offending parameter, when there is one example: limit required: description: >- On insufficient_scope: the scopes the request needs. Reissue the key with them. example: - submissions:write type: array items: type: string retry_after: type: number description: 'On scan_concurrency: seconds to wait before trying again.' example: 2 request_id: type: string description: Echoes X-Request-Id. Quote it when contacting support. example: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a required: - type - code - message - request_id SubmissionField: type: object properties: key: type: string example: email value: type: string example: ann@example.com required: - key - value SubmissionAttachment: type: object properties: key: type: string example: cv url: type: string mime_type: type: string example: application/pdf nullable: true required: - key - url - mime_type securitySchemes: api_key: scheme: bearer bearerFormat: fc_live_... type: http ```` ## Related topics - [Connect over MCP](/docs/connect.md) - [Lovable](/docs/ai/lovable.md) - [v0](/docs/ai/v0.md) - [Replit](/docs/ai/replit.md) - [ChatGPT](/docs/ai/chatgpt.md)