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

# Summarize findings

> Return aggregate finding counts (totals, assessment breakdown, unassessed severity × fixable matrix, suggested-action scalars) for the current organization, with optional filters.



## OpenAPI

````yaml https://api.app.chainloop.dev/openapi.yaml get /v1/findings/summary
openapi: 3.0.1
info:
  contact:
    email: support@chainloop.dev
    name: Chainloop Support
    url: https://chainloop.dev
  termsOfService: https://chainloop.dev/terms
  title: Chainloop Platform API
  version: '1.0'
servers:
  - url: https://api.app.chainloop.dev/
security:
  - bearerToken: []
tags:
  - description: AI-powered agent operations
    name: AgentsService
  - name: ArtifactService
  - name: AssessmentService
  - description: Service for polling the status of asynchronous operations
    name: AsyncOperationsService
  - name: AttestationsService
  - name: PolicyService
  - name: ComplianceService
  - name: ComponentService
  - name: EnvironmentsService
  - name: EvidenceService
  - name: FindingService
  - name: LogicalEnvironmentsService
  - name: ProductsService
  - name: ProjectsService
  - name: UserService
externalDocs:
  description: Chainloop Official Documentation
  url: https://docs.chainloop.dev
paths:
  /v1/findings/summary:
    get:
      tags:
        - FindingService
      summary: Summarize findings
      description: >-
        Return aggregate finding counts (totals, assessment breakdown,
        unassessed severity × fixable matrix, suggested-action scalars) for the
        current organization, with optional filters.
      operationId: FindingService_Summary
      parameters:
        - description: |-
            Filter by project name

            Filter findings by project name
          in: query
          name: project_name
          schema:
            type: string
        - description: |-
            Filter by project version name

            Filter findings by project version name
          in: query
          name: project_version_name
          schema:
            type: string
        - description: |-
            Filter by finding types

            Filter by one or more finding types
          explode: true
          in: query
          name: finding_type
          schema:
            items:
              enum:
                - FINDING_TYPE_UNSPECIFIED
                - FINDING_TYPE_VULNERABILITY
              type: string
            type: array
          style: form
        - description: |-
            Filter by one or more lifecycle statuses. Unset = no filter.

             - FINDING_STATUS_OPEN: OPEN: newly detected finding, not yet triaged or acted upon
             - FINDING_STATUS_IN_PROGRESS: IN_PROGRESS: finding is being investigated or actively remediated
             - FINDING_STATUS_RESOLVED: RESOLVED: finding has been fixed, mitigated, or otherwise closed (see resolution_reason for details)
             - FINDING_STATUS_REJECTED: REJECTED: finding has been dismissed by an operator (e.g. false positive, risk accepted, out of scope)
          explode: true
          in: query
          name: status
          schema:
            items:
              enum:
                - FINDING_STATUS_UNSPECIFIED
                - FINDING_STATUS_OPEN
                - FINDING_STATUS_IN_PROGRESS
                - FINDING_STATUS_RESOLVED
                - FINDING_STATUS_REJECTED
              type: string
            type: array
          style: form
        - description: >-
            Filter by artifact IDs (UUID); matches findings linked to any of the
            given artifacts
          explode: true
          in: query
          name: artifact_ids
          schema:
            items:
              type: string
            type: array
          style: form
        - description: Filter findings by associated software component ID (UUID)
          in: query
          name: component_id
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1FindingServiceSummaryResponse'
          description: A successful response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1BadRequestResponse'
          description: Bad Request - The request was invalid or cannot be served.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1UnauthorizedResponse'
          description: Unauthorized - Authentication is required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1PermissionDeniedResponse'
          description: Forbidden - You do not have permission to access this resource.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1InternalServerErrorResponse'
          description: Internal Server Error - An unexpected error occurred on the server.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
components:
  schemas:
    v1FindingServiceSummaryResponse:
      description: Aggregate finding counts for dashboards
      example:
        suggested_actions:
          fixable_unassessed: 5
          critical_high_unassessed: 5
          total_unassessed: 7
          exploitable_unassessed: 2
        by_severity:
          - severity: null
            count: 4
          - severity: null
            count: 4
        last_scanned_at: '2000-01-23T04:56:07.000Z'
        total: 0
        total_exploitable: 3
        by_effective_assessment_status:
          - count: 6
            status: ASSESSMENT_STATUS_UNSPECIFIED
          - count: 6
            status: ASSESSMENT_STATUS_UNSPECIFIED
        by_finding_type:
          - count: 9
            finding_type: FINDING_TYPE_UNSPECIFIED
          - count: 9
            finding_type: FINDING_TYPE_UNSPECIFIED
        unassessed_by_severity_fixable:
          - severity: FINDING_SEVERITY_UNSPECIFIED
            is_fixable: true
            count: 1
          - severity: FINDING_SEVERITY_UNSPECIFIED
            is_fixable: true
            count: 1
        total_fixable: 2
      properties:
        total:
          description: Total number of findings matching the request filters
          format: int32
          title: Total number of findings matching the request filters
          type: integer
        by_effective_assessment_status:
          description: >-
            Breakdown by effective assessment status (bucket with status unset =
            unassessed)
          items:
            $ref: '#/components/schemas/v1AssessmentStatusBucket'
          type: array
        unassessed_by_severity_fixable:
          description: Unassessed findings bucketed by severity × is_fixable
          items:
            $ref: '#/components/schemas/v1SeverityFixableBucket'
          title: Unassessed findings bucketed by severity and fixability
          type: array
        suggested_actions:
          $ref: '#/components/schemas/v1SuggestedActionCounts'
        by_finding_type:
          description: Breakdown by finding type
          items:
            $ref: '#/components/schemas/v1FindingTypeBucket'
          title: >-
            Breakdown by finding type (forward-compat for
            license/secret/misconfig findings)
          type: array
        total_exploitable:
          description: Total findings whose linked vulnerability is in the CISA KEV catalog
          format: int32
          title: >-
            Count of findings whose linked vulnerability is in the CISA KEV
            catalog (across all assessment states)
          type: integer
        total_fixable:
          description: Total findings with a fix available
          format: int32
          title: >-
            Count of findings with a fix available (fixed_version or
            recommendation) across all assessment states
          type: integer
        by_severity:
          description: Breakdown by severity across all findings
          items:
            $ref: '#/components/schemas/v1SeverityBucket'
          title: >-
            Breakdown by severity across all findings (not restricted to
            unassessed)
          type: array
        last_scanned_at:
          description: Most recent last_seen_at timestamp across matching findings
          format: date-time
          title: >-
            Most recent last_seen_at timestamp across matching findings; absent
            if no findings match
          type: string
      title: FindingServiceSummaryResponse
      type: object
    v1BadRequestResponse:
      description: Response for bad request
      example:
        code: 0
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 3
          description: >-
            The error code indicating the type of error. It's fixed to 3, which
            is the code for INVALID_ARGUMENT.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: BadRequestResponse
      type: object
    v1UnauthorizedResponse:
      description: Response for unauthorized access
      example:
        code: 6
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 16
          description: >-
            The error code indicating the type of error. It's fixed to 16, which
            is the code for UNAUTHENTICATED.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: UnauthorizedResponse
      type: object
    v1PermissionDeniedResponse:
      description: Response for permission denied
      example:
        code: 1
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 7
          description: >-
            The error code indicating the type of error. It's fixed to 7, which
            is the code for PERMISSION_DENIED.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: PermissionDeniedResponse
      type: object
    v1InternalServerErrorResponse:
      description: Response for internal server error
      example:
        code: 5
        details:
          - details
          - details
        message: message
      properties:
        code:
          default: 13
          description: >-
            The error code indicating the type of error. It's fixed to 13, which
            is the code for INTERNAL_ERROR.
          format: int32
          type: integer
        message:
          description: A human-readable message providing more details about the error.
          type: string
        details:
          description: Additional details about the error.
          items:
            type: string
          type: array
      required:
        - code
        - message
      title: InternalServerErrorResponse
      type: object
    rpcStatus:
      example:
        code: 5
        details:
          - '@type': '@type'
          - '@type': '@type'
        message: message
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string
        details:
          items:
            $ref: '#/components/schemas/protobufAny'
          type: array
      type: object
    v1AssessmentStatusBucket:
      description: >-
        AssessmentStatusBucket represents a count of findings sharing the same
        effective assessment status.

        When the status field is absent, the bucket represents unassessed
        findings.
      example:
        count: 6
        status: ASSESSMENT_STATUS_UNSPECIFIED
      properties:
        status:
          $ref: '#/components/schemas/v1AssessmentStatus'
        count:
          description: Count of findings in this bucket
          format: int32
          title: Count of findings in this bucket
          type: integer
      type: object
    v1SeverityFixableBucket:
      description: SeverityFixableBucket bucket findings by severity × is_fixable.
      example:
        severity: FINDING_SEVERITY_UNSPECIFIED
        is_fixable: true
        count: 1
      properties:
        severity:
          $ref: '#/components/schemas/v1FindingSeverity'
        is_fixable:
          description: Whether findings in this bucket are fixable
          title: >-
            Whether findings in this bucket have a fix available (fixed_version
            or recommendation)
          type: boolean
        count:
          description: Count of findings in this bucket
          format: int32
          title: Count of findings in this bucket
          type: integer
      type: object
    v1SuggestedActionCounts:
      description: >-
        SuggestedActionCounts are the four scalar counts driving the Suggested
        Actions card.

        All counts are restricted to unassessed findings matching the request's
        status/finding_type filters.
      example:
        fixable_unassessed: 5
        critical_high_unassessed: 5
        total_unassessed: 7
        exploitable_unassessed: 2
      properties:
        critical_high_unassessed:
          description: Unassessed findings with severity CRITICAL or HIGH
          format: int32
          title: Unassessed findings with severity CRITICAL or HIGH
          type: integer
        fixable_unassessed:
          description: Unassessed findings with a fix available
          format: int32
          title: Unassessed findings with a fixed_version or recommendation available
          type: integer
        exploitable_unassessed:
          description: >-
            Unassessed findings whose linked vulnerability is in the CISA KEV
            catalog
          format: int32
          title: >-
            Unassessed findings whose linked vulnerability is in the CISA KEV
            catalog
          type: integer
        total_unassessed:
          description: Total unassessed findings
          format: int32
          title: Total unassessed findings
          type: integer
      type: object
    v1FindingTypeBucket:
      description: FindingTypeBucket bucket findings by type.
      example:
        count: 9
        finding_type: FINDING_TYPE_UNSPECIFIED
      properties:
        finding_type:
          $ref: '#/components/schemas/v1FindingType'
        count:
          description: Count of findings in this bucket
          format: int32
          title: Count of findings in this bucket
          type: integer
      type: object
    v1SeverityBucket:
      description: >-
        SeverityBucket counts findings at a given severity across all assessment
        states.
      example:
        severity: null
        count: 4
      properties:
        severity:
          $ref: '#/components/schemas/v1FindingSeverity'
        count:
          description: Count of findings in this bucket
          format: int32
          title: Count of findings in this bucket
          type: integer
      type: object
    protobufAny:
      additionalProperties:
        type: object
      example:
        '@type': '@type'
      properties:
        '@type':
          type: string
      type: object
    v1AssessmentStatus:
      default: ASSESSMENT_STATUS_UNSPECIFIED
      enum:
        - ASSESSMENT_STATUS_UNSPECIFIED
        - ASSESSMENT_STATUS_NOT_AFFECTED
        - ASSESSMENT_STATUS_AFFECTED
        - ASSESSMENT_STATUS_UNDER_INVESTIGATION
        - ASSESSMENT_STATUS_FIXED
      title: AssessmentStatus represents the OpenVEX-aligned status
      type: string
    v1FindingSeverity:
      default: FINDING_SEVERITY_UNSPECIFIED
      description: >-
        FindingSeverity represents the severity level of a finding. Lives in

        shared_messages.proto so both finding.proto and assessment.proto can use
        it

        without creating an import cycle (finding.proto imports assessment.proto
        for

        AssessmentStatus, and assessment.proto needs FindingSeverity for the

        severity field on AssessmentItem).
      enum:
        - FINDING_SEVERITY_UNSPECIFIED
        - FINDING_SEVERITY_CRITICAL
        - FINDING_SEVERITY_HIGH
        - FINDING_SEVERITY_MEDIUM
        - FINDING_SEVERITY_LOW
        - FINDING_SEVERITY_INFO
        - FINDING_SEVERITY_UNKNOWN
      type: string
    v1FindingType:
      default: FINDING_TYPE_UNSPECIFIED
      description: |-
        FindingType represents the type of security finding. Lives in
        shared_messages.proto for the same reason as FindingSeverity:
        assessment.proto needs it for the ListEffective query tuples without
        creating an import cycle with finding.proto.
      enum:
        - FINDING_TYPE_UNSPECIFIED
        - FINDING_TYPE_VULNERABILITY
      type: string
  securitySchemes:
    bearerToken:
      description: Bearer token for authentication
      type: http
      scheme: bearer
      bearerFormat: JWT

````