> ## Documentation Index > Fetch the complete documentation index at: https://docs.formbox.app/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a list of submissions > Retrieve a paginated list of submissions for a given form for the authenticated organization. ## OpenAPI ````yaml get /submissions openapi: 3.1.0 info: title: Formbox API description: Formbox is an all in one forms solution for your business. version: 0.0.1 contact: name: Formbox Support email: support@formbox.app url: https://docs.formbox.app/api-reference servers: - url: https://app.formbox.app/api/v1 description: Production API security: [] paths: /submissions: get: tags: - Submissions summary: Retrieve a list of submissions description: >- Retrieve a paginated list of submissions for a given form for the authenticated organization. operationId: getSubmissions parameters: - in: query name: formId description: The unique ID of the form. schema: type: string description: The unique ID of the form. required: true - in: query name: search description: Search for a submission by its content. schema: type: string description: Search for a submission by its content. - in: query name: isSpam description: Filter submissions by spam status. Pass `true` or `false`. schema: type: string enum: - 'true' - 'false' description: Filter submissions by spam status. Pass `true` or `false`. - in: query name: page description: The page number for pagination. required: false example: 1 schema: $ref: '#/components/schemas/PageQueryParam' - in: query name: pageSize description: The number of items per page. schema: type: integer exclusiveMinimum: 0 maximum: 100 default: 20 description: The number of items per page. example: 50 - in: header name: api-key description: The API key. schema: $ref: '#/components/schemas/ApiKeyHeaderValue' required: true responses: '200': description: A list of submissions. headers: Retry-After: description: Seconds until the current rate limit window resets. example: '60' schema: $ref: '#/components/schemas/RetryAfterHeader' required: true X-RateLimit-Limit: description: The number of requests allowed in the current rate limit window. example: '100' schema: $ref: '#/components/schemas/RateLimitLimitHeader' required: true X-RateLimit-Remaining: description: >- The number of requests remaining in the current rate limit window. example: '99' schema: $ref: '#/components/schemas/RateLimitRemainingHeader' required: true X-RateLimit-Reset: description: The Unix timestamp when the current rate limit window resets. example: '1711910400' schema: $ref: '#/components/schemas/RateLimitResetHeader' required: true content: application/json: schema: $ref: '#/components/schemas/SubmissionsResponse' '401': $ref: '#/components/responses/401' '403': description: >- Your API key requires `read` or `full` access scope to list submissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - forbidden description: A short code indicating the error code returned. example: forbidden message: type: string description: A human readable explanation of what went wrong. example: >- Your API key requires read or full access scope to list submissions. required: - code - message required: - error '422': description: >- `formId` is required. Ensure `page` and `pageSize` are positive integers and that `isSpam` is `true` or `false` if provided. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unprocessable_entity description: A short code indicating the error code returned. example: unprocessable_entity message: type: string description: A human readable explanation of what went wrong. example: >- formId: Required. page and pageSize must be positive integers. isSpam must be true or false. required: - code - message required: - error '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' security: - token: [] components: schemas: PageQueryParam: type: integer exclusiveMinimum: 0 default: 1 description: The page number for pagination. example: 1 ApiKeyHeaderValue: type: string description: The API key. title: api-key RetryAfterHeader: type: string RateLimitLimitHeader: type: string RateLimitRemainingHeader: type: string RateLimitResetHeader: type: string SubmissionsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/SubmissionResponse' description: The list of items. meta: $ref: '#/components/schemas/SubmissionsMeta' description: Extra metadata about the response. pagination: $ref: '#/components/schemas/PaginationMetadata' required: - data - meta - pagination SubmissionResponse: type: object properties: id: type: string description: The unique ID of the submission. formId: type: string description: The ID of the form. isSpam: type: boolean description: Whether the submission is spam. answers: type: array items: $ref: '#/components/schemas/SubmissionAnswer' description: The answers for the submission. files: type: array items: $ref: '#/components/schemas/SubmissionFile' description: The files for the submission. createdAt: type: string description: The date the submission was created. updatedAt: type: string description: The date the submission was last updated. required: - id - formId - isSpam - createdAt - updatedAt title: Submission SubmissionsMeta: type: object properties: total: type: number description: The total number of submissions. totalInbox: type: number description: The total number of inbox submissions. totalSpam: type: number description: The total number of spam submissions. required: - total - totalInbox - totalSpam description: Extra metadata about the submissions response. PaginationMetadata: type: object properties: totalPages: type: number description: The total number of pages. currentPage: type: number description: The current page number. nextPage: type: - number - 'null' description: The next page number. previousPage: type: - number - 'null' description: The previous page number. required: - totalPages - currentPage description: Pagination metadata. SubmissionAnswer: type: object properties: id: type: string description: The answer ID. label: type: string description: The answer label. value: type: string description: The answer value. required: - id - label - value SubmissionFile: type: object properties: id: type: string description: The file ID. name: type: string description: The file name. type: type: string description: The file type. size: type: number description: The file size in bytes. url: type: string description: The file URL. createdAt: type: string description: The date the file was created. updatedAt: type: string description: The date the file was last updated. required: - id - name - type - size - url - createdAt - updatedAt responses: '401': description: >- No valid API key was provided. Include your API key in the `api-key` request header. You can generate API keys in your Formbox organization settings. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized description: A short code indicating the error code returned. example: unauthorized message: type: string description: A human readable explanation of what went wrong. example: >- No API key provided. Pass your API key in the api-key header. required: - code - message required: - error '429': description: >- Too many requests. Check the X-RateLimit-* headers and retry after the reset time. headers: Retry-After: description: Seconds until the current rate limit window resets. example: '60' schema: $ref: '#/components/schemas/RetryAfterHeader' required: true X-RateLimit-Limit: description: The number of requests allowed in the current rate limit window. example: '100' schema: $ref: '#/components/schemas/RateLimitLimitHeader' required: true X-RateLimit-Remaining: description: The number of requests remaining in the current rate limit window. example: '99' schema: $ref: '#/components/schemas/RateLimitRemainingHeader' required: true X-RateLimit-Reset: description: The Unix timestamp when the current rate limit window resets. example: '1711910400' schema: $ref: '#/components/schemas/RateLimitResetHeader' required: true content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded description: A short code indicating the error code returned. example: rate_limit_exceeded message: type: string description: A human readable explanation of what went wrong. example: Too many requests. Please slow down and try again shortly. required: - code - message required: - error '500': description: An unexpected error occurred on the server. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - internal_server_error description: A short code indicating the error code returned. example: internal_server_error message: type: string description: A human readable explanation of what went wrong. example: >- An internal server error occurred. Please contact support if the problem persists. required: - code - message required: - error ````