> ## Documentation Index > Fetch the complete documentation index at: https://docs.dotportion.com/llms.txt > Use this file to discover all available pages before exploring further. # List submissions > Candidate submissions across your assessments, newest first. CURSOR-paginated, because this collection grows without bound. Walk the collection by following `meta.next_cursor` until it comes back `null`. Never build a cursor yourself — the encoding is ours to change. Note the status vocabulary: there is no `completed`. A graded submission is `evaluated`. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/submissions openapi: 3.1.0 info: title: Dotportion API version: 1.0.0 description: >- Create assessments, invite candidates, and pull back hiring reports. Authenticate with an API key as a bearer token. Keys are scoped to a single organization and cannot reach another one. Use a `sk_test_` key to develop against deterministic sample data. servers: - url: https://app.dotportion.com description: Production security: - bearerAuth: [] tags: - name: Challenges description: The challenge library available to you. - name: Assessments description: Job postings built from a challenge. - name: Invitations description: Candidate invitations and their lifecycle. - name: Submissions description: Candidate attempts, reports and event logs. - name: Members description: Your organization’s team. - name: Account description: Plan, usage and branding. paths: /api/v1/submissions: get: tags: - Submissions summary: List submissions description: >- Candidate submissions across your assessments, newest first. CURSOR-paginated, because this collection grows without bound. Walk the collection by following `meta.next_cursor` until it comes back `null`. Never build a cursor yourself — the encoding is ours to change. Note the status vocabulary: there is no `completed`. A graded submission is `evaluated`. operationId: listSubmissions parameters: - name: assessment_id in: query required: false description: Only this assessment. schema: type: string format: uuid - name: candidate_email in: query required: false description: Only this candidate. schema: type: string format: email - name: status in: query required: false description: >- Restrict to one submission status. Note there is no `completed` — a graded submission is `evaluated`. schema: type: string enum: - initialized - in_progress - paused - submitted - evaluating - evaluated - expired - failed - name: since in: query required: false description: ISO-8601 lower bound on created_at. schema: type: string format: date-time - name: until in: query required: false description: ISO-8601 upper bound on created_at. schema: type: string format: date-time - name: cursor in: query required: false description: From a previous `meta.next_cursor`. Opaque. schema: type: string - name: limit in: query required: false description: Items per page, max 100. schema: type: integer default: 20 responses: '200': description: Success. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: data: - id: 00000000-0000-4000-8000-000000000031 assessment_id: 00000000-0000-4000-8000-000000000011 challenge: name: LRU Cache slug: lru-cache candidate: email: katherine@example.com name: Katherine Johnson status: evaluated started_at: '2026-01-15T12:00:00.000Z' submitted_at: '2026-01-15T12:00:00.000Z' evaluated_at: '2026-01-15T12:00:00.000Z' paused_total_seconds: 120 budget: dollars_used: 1.25 dollars_cap: 3 created_at: '2026-01-15T12:00:00.000Z' - id: 00000000-0000-4000-8000-000000000032 assessment_id: 00000000-0000-4000-8000-000000000011 challenge: name: LRU Cache slug: lru-cache candidate: email: alan@example.com name: Alan Turing status: in_progress started_at: '2026-01-15T12:00:00.000Z' submitted_at: null evaluated_at: null paused_total_seconds: 0 budget: dollars_used: 0.4 dollars_cap: 3 created_at: '2026-01-15T12:00:00.000Z' - id: 00000000-0000-4000-8000-000000000033 assessment_id: 00000000-0000-4000-8000-000000000011 challenge: name: LRU Cache slug: lru-cache candidate: email: grace@example.com name: Grace Hopper status: submitted started_at: '2026-01-15T12:00:00.000Z' submitted_at: '2026-01-15T12:00:00.000Z' evaluated_at: null paused_total_seconds: 0 budget: dollars_used: 2.1 dollars_cap: 3 created_at: '2026-01-15T12:00:00.000Z' meta: request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c next_cursor: null has_more: false '400': description: >- INVALID_INPUT — A query parameter or body field failed validation. `details` names the fields. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INVALID_INPUT message: Invalid request details: formErrors: [] fieldErrors: name: - String must contain at least 1 character(s) request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '401': description: INVALID_TOKEN — The key is missing, malformed, revoked, or expired. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INVALID_TOKEN message: Invalid or revoked API key request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '403': description: >- INSUFFICIENT_SCOPE — The key doesn't carry the scope this endpoint needs. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INSUFFICIENT_SCOPE message: 'This API key lacks the required scope: write.' request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '429': description: RATE_LIMITED — The key exhausted its hourly quota for this class. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: RATE_LIMITED message: >- Rate limit exceeded for write requests (200/hour). Retry after 2026-01-15T13:00:00.000Z. details: limit: 200 remaining: 0 reset: 1768482000 request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '500': description: INTERNAL_ERROR — Something failed on our side. Quote the request_id. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INTERNAL_ERROR message: Internal server error request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c security: - bearerAuth: [] components: headers: XRequestId: description: Correlation id for this request. Quote it in support requests. schema: type: string XRateLimitLimit: description: Requests permitted per hour for this quota class. schema: type: integer XRateLimitRemaining: description: Requests left in the current window. schema: type: integer XRateLimitReset: description: Unix time (seconds) when the window resets. schema: type: integer RetryAfter: description: Seconds to wait before retrying. Present on 429. schema: type: integer schemas: SuccessEnvelope: type: object description: >- Every successful response. `meta` carries the request id and any pagination. properties: data: description: The resource, or an array of them. oneOf: - type: object - type: array items: type: object meta: $ref: '#/components/schemas/Meta' required: - data - meta ErrorEnvelope: type: object description: Every failure. Switch on `error.code`, not on the message. properties: error: type: object properties: code: type: string enum: - INVALID_INPUT - INVALID_TOKEN - PLAN_LIMIT_REACHED - INSUFFICIENT_SCOPE - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR description: Stable machine-readable code. message: type: string description: Human-readable. May be reworded. details: description: Field-level validation errors, when applicable. request_id: type: string required: - code - message - request_id required: - error Meta: type: object properties: request_id: type: string description: Correlation id for this request. page: type: integer description: 'Offset pagination: current page.' page_size: type: integer description: 'Offset pagination: page size.' total: type: integer description: 'Offset pagination: total matching records.' has_more: type: boolean description: Whether another page exists. next_cursor: type: - string - 'null' description: >- Cursor pagination: pass as `cursor` for the next page. `null` means the end. Opaque — never construct one. required: - request_id securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your API key, live (`sk_live_…`) or test (`sk_test_…`). Create one in Settings → API keys. Send it as `Authorization: Bearer ` — never in a query string. ````