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

# List scans

> Returns scans for the team attached to your API key. This route requires a key whose role includes the `scans.read` permission.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/scans
openapi: 3.1.0
info:
  title: Gecko SAST Scanner API
  version: v1
  description: >-
    Use the Gecko API to launch scans and read scan, repository, and
    vulnerability data for your active team.
servers:
  - url: https://app.gecko.security
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Scans
    description: Launch scans and read scan-level data.
  - name: Repositories
    description: Read repository inventory and repository vulnerability data.
  - name: Vulnerabilities
    description: Read vulnerability data across your active team.
  - name: Utility
    description: Service health and utility endpoints.
paths:
  /api/v1/scans:
    get:
      tags:
        - Scans
      summary: List scans
      description: >-
        Returns scans for the team attached to your API key. This route requires
        a key whose role includes the `scans.read` permission.
      operationId: getApiV1Scans
      parameters:
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A paginated list of scans.
          headers:
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanListResponse'
              example:
                version: v1
                data:
                  - id: f5d35de5-8fc8-4a01-8e28-3bae5d6d26ad
                    name: Sample Scan
                    status: completed
                    isDone: true
                    createdAt: '2025-04-22T15:34:53.674Z'
                    endAt: '2025-04-22T16:08:22.115Z'
                    programmingLanguage: TypeScript
                    progress: 100
                    vulnerabilityCounts:
                      total: 42
                      critical: 3
                      high: 11
                      medium: 20
                      low: 8
                pagination:
                  total: 123
                  limit: 50
                  offset: 0
                  hasMore: true
                filters:
                  status: completed
                  language: typescript
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: >-
            The API key is valid, but the key does not include the `scans.read`
            permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: API key lacks scans.read permission
        '429':
          $ref: '#/components/responses/RateLimitedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    status:
      name: status
      in: query
      required: false
      description: Filter scans by status.
      schema:
        type: string
      example: completed
    language:
      name: language
      in: query
      required: false
      description: Filter scans by programming language.
      schema:
        type: string
      example: typescript
    limit:
      name: limit
      in: query
      required: false
      description: >-
        Maximum number of results to return. Gecko defaults to `100` and caps
        the value at `1000`.
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
      example: 50
    offset:
      name: offset
      in: query
      required: false
      description: Number of results to skip before Gecko starts returning rows.
      schema:
        type: integer
        default: 0
        minimum: 0
      example: 0
  headers:
    XRateLimitRemaining:
      description: Requests remaining in the current one-hour window for the API key.
      schema:
        type: integer
    XRateLimitReset:
      description: >-
        ISO 8601 timestamp for when the current one-hour rate-limit window
        resets.
      schema:
        type: string
        format: date-time
    RetryAfter:
      description: Seconds to wait before retrying the request.
      schema:
        type: integer
  schemas:
    ScanListResponse:
      type: object
      required:
        - version
        - data
        - pagination
        - filters
      properties:
        version:
          type: string
          const: v1
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScanSummary'
        pagination:
          $ref: '#/components/schemas/Pagination'
        filters:
          $ref: '#/components/schemas/ScanListFilters'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        details:
          type:
            - string
            - 'null'
        hint:
          type:
            - string
            - 'null'
    ScanSummary:
      type: object
      required:
        - id
        - name
        - status
        - isDone
        - createdAt
        - endAt
        - programmingLanguage
        - progress
        - vulnerabilityCounts
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type:
            - string
            - 'null'
        isDone:
          type: boolean
        createdAt:
          type: string
          format: date-time
        endAt:
          type:
            - string
            - 'null'
          format: date-time
        programmingLanguage:
          type:
            - string
            - 'null'
        progress:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 100
        vulnerabilityCounts:
          $ref: '#/components/schemas/ScanVulnerabilityCounts'
    Pagination:
      type: object
      required:
        - total
        - limit
        - offset
        - hasMore
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        hasMore:
          type: boolean
    ScanListFilters:
      type: object
      required:
        - status
        - language
      properties:
        status:
          type:
            - string
            - 'null'
        language:
          type:
            - string
            - 'null'
    ScanVulnerabilityCounts:
      type: object
      required:
        - total
        - critical
        - high
        - medium
        - low
      properties:
        total:
          type: integer
        critical:
          type: integer
        high:
          type: integer
        medium:
          type: integer
        low:
          type: integer
  responses:
    BadRequestError:
      description: The request parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Limit cannot exceed 1000
    UnauthorizedError:
      description: The API key is missing, malformed, or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingKey:
              value:
                error: API key is required
            badFormat:
              value:
                error: Invalid API key format
            badKey:
              value:
                error: Invalid API key
    RateLimitedError:
      description: The API key reached the per-hour request limit.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Rate limit exceeded
    InternalServerError:
      description: Gecko failed to process the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Internal server error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Team-scoped Gecko API key. Keys start with `gk_`.

````