> ## 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. # Count submissions > Counts the submissions matching the filters instead of returning them, so you can see the size of an answer before you page through it. Takes the same filters as the list. Pass group_by to count by day, week, month, country, spam, read or a submitted field, and the largest 20 groups come back with the rest in `other`. A count that does not finish in time returns what it reached with `exact: false`; narrow the date range for an exact one. ## OpenAPI ````yaml https://api.formcarry.com/docs-json get /v1/forms/{form_id}/submissions/summary 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/forms/{form_id}/submissions/summary: get: tags: - submissions summary: Count submissions description: >- Counts the submissions matching the filters instead of returning them, so you can see the size of an answer before you page through it. Takes the same filters as the list. Pass group_by to count by day, week, month, country, spam, read or a submitted field, and the largest 20 groups come back with the rest in `other`. A count that does not finish in time returns what it reached with `exact: false`; narrow the date range for an exact one. operationId: SubmissionsController_summary parameters: - name: form_id required: true in: path description: >- The form's id, as shown in the dashboard and in the form's endpoint URL example: AbC123xyz schema: type: string - 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: group_by required: false in: query description: >- Count by this instead of returning one total: day, week, month, country, spam, read, or field: for a submitted field. Leave it out for the total alone. example: country schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SubmissionSummary' '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: >- group_by must be one of day, week, month, country, spam, read, or field:. param: group_by 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 '404': description: No such form for this key, or no such submission on it. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: form_not_found: summary: form_not_found value: error: type: invalid_request_error code: form_not_found message: No form with that id is accessible with this key. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a submission_not_found: summary: submission_not_found value: error: type: invalid_request_error code: submission_not_found message: No submission with that id exists on this form. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '422': description: The request took too long; narrow the date range and retry. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: query_timeout: summary: query_timeout value: error: type: invalid_request_error code: query_timeout message: >- The request did not finish in time. Narrow the date range with created_after and created_before and try again. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a '429': description: Slow down and retry after the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests. request_id: 2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a 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: SubmissionSummary: type: object properties: total: type: number example: 428 description: Submissions matching the filters. exact: type: boolean description: >- False when the count did not finish in time, so total and the counts are a floor rather than the whole set. Narrow the date range for an exact answer. group_by: type: string nullable: true example: country description: What the counts are grouped by, or null for the total alone. buckets: description: Largest first, up to 20. type: array items: $ref: '#/components/schemas/SubmissionBucket' other: type: number example: 12 description: Submissions in groups outside the 20 returned. truncated: type: boolean description: >- True when group_by passed 10,000 distinct values, so some are missing from buckets though their submissions still count in total and other. Always false without group_by. required: - total - exact - group_by - buckets - other - truncated ErrorEnvelope: type: object properties: error: $ref: '#/components/schemas/ErrorBody' required: - error SubmissionBucket: type: object properties: key: type: string example: DE description: The value counted. "" is the group with no value. count: type: number example: 120 required: - key - count 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 securitySchemes: api_key: scheme: bearer bearerFormat: fc_live_... type: http ```` ## Related topics - [Automatic Spam Protection](/docs/features/spam-protection.md) - [Framer](/docs/builders/framer.md) - [List a form's fields](/docs/api-reference/forms/list-a-forms-fields.md) - [Connect over MCP](/docs/connect.md) - [Read what happened to submissions](/docs/api-reference/submissions/read-what-happened-to-submissions.md)