---
title: "List secret occurrences"
method: GET
path: "/v1/occurrences/secrets"
tags: ["Internal Secret Occurrences"]
---

# List secret occurrences

`GET /v1/occurrences/secrets`

List occurrences of secrets in the monitored perimeter.

## Query parameters

- `cursor` string
- `page` integer
- `per_page` integer
- `date_before` string, datetime — Entries found before this date.
- `date_after` string, datetime — Entries found after this date.
- `source_id` integer
- `source_name` string — Entries matching this source name search.
- `source_type` 'bitbucket' | 'bitbucket_cloud' | 'github' | 'gitlab' | 'azure_devops' | 'slack' | 'jira_cloud' | 'confluence_cloud' | 'microsoft_teams' | 'confluence_data_center' | 'jira_data_center' | 'aws_ecr' | 'azure_cr' | 'google_artifact' | 'jfrog_artifact' | 'docker_hub' | 'servicenow' | 'sharepoint_online' | 'sharepoint_online_drive' | 'sharepoint_online_pages' | 'microsoft_onedrive' | 'custom_source' — Filter by source type.
- `source_monitoring_status` string — Keep only occurrences whose source's real-time monitoring status is one of the given (comma-separated) buckets. Requires the monitoring-status feature to be enabled for the workspace; otherwise the parameter is ignored.
- `incident_id` integer
- `incident_assignee_id` integer
- `presence` 'present' | 'removed' — Entries that have the following presence status.
- `author_name` string — Entries matching this author name search.
- `author_info` string — Entries matching this author email search.
- `sha` string — Entries starting with the commit sha search string.
- `filepath` string — Entries matching this filepath search.
- `severity` 'critical' | 'high' | 'medium' | 'low' | 'info' | 'unknown' — Filter occurrences by the severity of their related incident. Can specify multiple values separated by commas.
- `status` 'IGNORED' | 'TRIGGERED' | 'ASSIGNED' | 'RESOLVED' — Filter occurrences by the status of their related incident. Can specify multiple values separated by commas.
- `validity` 'valid' | 'invalid' | 'failed_to_check' | 'no_checker' | 'unknown' — Filter occurrences by the validity of their related secret. Can specify multiple values separated by commas.
- `tags` 'DEFAULT_BRANCH' | 'FROM_HISTORICAL_SCAN' | 'CHECK_RUN_SKIP_FALSE_POSITIVE' | 'CHECK_RUN_SKIP_LOW_RISK' | 'CHECK_RUN_SKIP_TEST_CRED' | 'PUBLIC' | 'PUBLICLY_EXPOSED' | 'PUBLICLY_LEAKED' | 'REGRESSION' | 'SENSITIVE_FILE' | 'TEST_FILE' | 'FALSE_POSITIVE' | 'VAULTED' | 'NONE' — Occurrences with one of the following tags. Use `NONE` if you want to filter occurrences with no tags.
- `exclude_tags` 'DEFAULT_BRANCH' | 'FROM_HISTORICAL_SCAN' | 'CHECK_RUN_SKIP_FALSE_POSITIVE' | 'CHECK_RUN_SKIP_LOW_RISK' | 'CHECK_RUN_SKIP_TEST_CRED' | 'PUBLIC' | 'PUBLICLY_EXPOSED' | 'PUBLICLY_LEAKED' | 'REGRESSION' | 'SENSITIVE_FILE' | 'TEST_FILE' | 'FALSE_POSITIVE' | 'VAULTED' | 'NONE' — Exclude occurrences with any of the following tags (comma-separated). Use `NONE` to exclude occurrences with no tags.
- `ordering` 'date' | '-date'

## Response `200`

List occurrences

- object[]
  - `id` integer
  - `incident_id` integer
  - `kind` 'realtime' | 'historical'
  - `source` object
    - `id` integer
    - `url` string, uri
    - `type` string
    - `full_name` string
    - `health` 'safe' | 'unknown' | 'at_risk'
    - `default_branch` string, nullable — Default branch of the source repository.
    - `default_branch_head` string, nullable — Reference of the HEAD of the default branch.
    - `open_incidents_count` integer — Number of open secret incidents with at least one occurrence on this source.
    - `closed_incidents_count` integer — Number of closed secret incidents with at least one occurrence on this source.
    - `secret_incidents_breakdown` object — Detailed count of secret incidents linked to this source.
      - `open_secret_incidents` object
        - `total` integer
        - `severity_breakdown` object
          - `critical` integer
          - `high` integer
          - `medium` integer
          - `low` integer
          - `info` integer
          - `unknown` integer
      - `closed_secret_incidents` object
        - `total` integer
        - `severity_breakdown` object
          - `critical` integer
          - `high` integer
          - `medium` integer
          - `low` integer
          - `info` integer
          - `unknown` integer
    - `visibility` string
    - `external_id` string — VCS identifier of the source (e.g.: the GitHub id for a GitHub repository). Warning: external_id is a string because some VCS ids can be UUIDs.
    - `source_criticality` string — Criticality of the source.
    - `last_scan` object, nullable
      - `date` string, date-time — Creation date of this historical scan
      - `status` 'launched' | 'pending' | 'running' | 'finished' | 'failed' | 'canceled' | 'too_large' | 'timeout' | 'skipped' | 'pending_timeout' | 'running_failed' | 'running_cancelled'
      - `failing_reason` string — Failure reason of the historical scan, if status is failed
      - `commits_scanned` integer — Number of commits scanned
      - `branches_scanned` integer — Number of branches scanned
      - `duration` string — Historical scan duration
    - `monitored` boolean — Deprecated: use `monitoring_status` to read a source's real-time monitoring state (`monitoring_status` distinguishes disabled, archived, unreachable and deleted-on-remote sources, which this boolean cannot). Whether the source is currently monitored by GitGuardian.
    - `monitoring_status` 'active' | 'disabled' | 'unreachable' | 'archived' | 'deleted_on_remote' — Real-time monitoring status of the source. Note: the `unreachable` and `disabled` buckets are not fully backed yet and may report `active` until the supporting backend lands.
    - `provider_metadata` object — Metadata from the upstream provider. Fields depend on integration; absent concepts are represented with conservative defaults (e.g. archived false).
      - `archived` boolean, required — Whether the resource is archived on the provider (e.g. archived GitHub repository). False when not applicable or when the provider does not expose this information.
    - `deleted` boolean — Whether the source has been deleted
  - `author_name` string
  - `author_info` string
  - `date` string, date-time
  - `url` string
  - `matches` object[]
    - `name` string, required
    - `indice_start` integer, required
    - `indice_end` integer, required
    - `pre_line_start` integer, nullable, required
    - `pre_line_end` integer, nullable, required
    - `post_line_start` integer, nullable, required
    - `post_line_end` integer, nullable, required
  - `tags` string[]
  - `incident_name` string — Human-readable name combining detector information
  - `sha` string, nullable
  - `presence` 'present' | 'removed'
  - `filepath` string, nullable — This is filename for old models with incomplete data
  - `change_type` 'addition' | 'deletion' | 'context', nullable — Type of change in the VCS commit (git diff line type)

## Other responses

- `400` — Invalid data
- `401` — Invalid API key
- `503` — API under maintenance

---

[API](https://skmtc.net/gitguardian/apis/gitguardian-api.md) · [All operations](https://skmtc.net/gitguardian/apis/gitguardian-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gitguardian/gitguardian-api/revisions/511b067cdcb1/schema)