> ## Documentation Index > Fetch the complete documentation index at: https://docs.semgrep.dev/llms.txt > Use this file to discover all available pages before exploring further. # List Scans > List the scans associated with a particular project from the past 30 days. ## OpenAPI ````yaml /public_v2.openapi.yaml post /api/v2/deployments/{deploymentId}/projects/{projectId}/scans/list openapi: 3.0.3 info: title: Semgrep API description: >- The API v2 is currently a work in progress as we expand and improve our platform capabilities. There are no current plans to deprecate the [v1 API](/api/v1/docs) – we remain committed to supporting existing integrations and will ensure that all v1 use cases are fully supported in v2 before any deprecation occurs. ## API Maturity Levels Each endpoint in the v2 API is marked with a maturity badge to help you understand its current state: 🚧 **Experimental** - Use at your own risk. This endpoint was not originally designed for third-party use or is under active development. Expect significant breaking changes. ⚠️ **Beta** - This endpoint is being refined. We will communicate breaking changes to Beta partners as we tweak the implementation. ✅ **Stable** - No breaking changes will be made to this API. You can confidently build production integrations against these endpoints. We recommend using Stable endpoints for production applications and treating Experimental/Beta endpoints as previews of upcoming functionality. This API is documented in the **OpenAPI format**. # Authentication The API supports authentication with an API token with the "Web API" permission, without limited scopes of access. You can provision an API token [from the Settings page](https://semgrep.dev/orgs/-/settings/tokens). # Terms of Use Please note, the materials made available herein are subject to the [Semgrep Terms of Use](https://semgrep.dev/resources/website-terms/), and your access or use of any of the same is your acknowledgment and acceptance of the such terms.
___ contact: email: support@semgrep.com version: v2.0.0.alpha x-logo: url: https://semgrep.dev/images/SemgrepLogoWithTextWithMargin.svg backgroundColor: '#fafafa' altText: Semgrep logo servers: [] security: [] tags: - name: AiFixJobsService description: Manage AI fix jobs for automated security fixes x-displayName: AI Fix Jobs x-group: AI Fix Jobs - name: AiTasksService description: Manage AI tasks, such as triage, auto-triage, and issue tagging backfill x-displayName: Ai Tasks x-group: Ai Tasks - name: AutofixService description: Trigger automated fixes for SAST, AI SAST, and SCA issues. x-displayName: Autofix x-group: Autofix - name: AutomationsService description: >- Automations are a way to automatically take actions on findings based on certain conditions. x-displayName: Automations x-group: Automations - name: AutotriageFeedbackService description: Feedback for the quality of autotriage, guidance or autofix x-displayName: Autotriage Feedback x-group: Autotriage Feedback - name: ChecklistService description: Manage onboarding checklist x-displayName: Onboarding Checklist x-group: Onboarding Checklist - name: DeploymentProductsService description: Manage deployment product configurations. x-displayName: Deployment Products x-group: Deployment Products - name: DeploymentService description: Manage deployment and its resources. x-displayName: Deployment x-group: Deployment - name: DeploymentSsoProvidersService description: Manage Deployment SSO Providers x-displayName: Deployment SSO Providers x-group: Deployment SSO Providers - name: DeploymentTagService description: Assign tags to a deployment. x-displayName: Deployment Tags x-group: Deployment Tags - name: DeploymentsService description: >- Deployments encapsulate your organization's security organization, with multiple projects, policies, and integrations. As the root object of the organization, they're similarly the root object of the API. x-displayName: Deployments x-group: Deployments - name: EditorService description: Run Semgrep patterns against target code in the editor playground x-displayName: Editor x-group: Editor - name: ExternalTicketingService description: APIs that power the External Ticketing experience. x-displayName: External Ticketing x-group: External Ticketing - name: FeatureRolloutsService description: View feature flags rolled out to all deployments x-displayName: Feature Rollouts x-group: Feature Rollouts - name: IgnoresService description: >- API for managing global ignores. See https://semgrep.dev/docs/ignoring-files-folders-code x-displayName: Global Ignores x-group: Global Ignores - name: InfrastructureConfigurationsService description: Infrastructure configuration information. x-displayName: Infrastructure Configurations x-group: Infrastructure Configurations - name: IssuesService description: Manage findings found by Semgrep scans x-displayName: Issues x-group: Issues - name: ManagedScanSettingsService description: Settings that affect all of a deployment's managed scans x-displayName: Managed Scan Settings x-group: Managed Scan Settings - name: MemoriesService description: Memories help reduce noise from findings. x-displayName: Memories x-group: Memories - name: MiscService description: Miscellaneous endpoints x-displayName: Misc x-group: Misc - name: NotificationRulesService description: Setup rules to get notified about new findings x-displayName: Notification Rules x-group: Notification Rules - name: NotificationWebhooksService description: Manage webhook endpoints for deployment notifications. x-displayName: Notification Webhooks x-group: Notification Webhooks - name: NotificationsService description: Notifications show in-app toasts to users. x-displayName: Notifications x-group: Notifications - name: PoliciesService description: >- View and manage the Policies of your organization. Deployments on the Unified Policies model use the [Policies V2 API](/api/v2/docs/#tag/PoliciesV2Service) instead; this service stops working after the migration. x-displayName: Policies x-group: Policies - name: PoliciesV2Service description: >- Declarative management of detection and remediation policies for deployments on the Unified Policies model. Designed for GitOps-style reconciliation: read the current bundle, edit it, preview the diff with a dry run, then apply it strictly with optimistic concurrency control. x-displayName: Policies V2 x-group: Policies V2 - name: ProjectManagedScanSettingsService description: Settings that affect a specific project's managed scans x-displayName: Projects – Managed Scan Settings x-group: Projects – Managed Scan Settings - name: ProjectsService description: >- Projects are groups of files that are scanned by Semgrep. These normally correspond to repositories. x-displayName: Projects x-group: Projects - name: ReportsService description: APIs for Reporting Dashboards x-displayName: Reporting x-group: Reporting - name: ReviewCommentProductContentService description: >- Review comment product content is a way to add additional per-product information to a review comment. x-displayName: Review Comment Product Content x-group: Review Comment Product Content - name: RuleboardService description: >- The [Policies API](/api/v2/docs/#tag/PoliciesService) is *strongly* recommended. It is also newer than this Ruleboard service. Deployments on the Unified Policies model use the [Policies V2 API](/api/v2/docs/#tag/PoliciesV2Service) instead; this service stops working after the migration. Manage Ruleboards (sets of policies). x-displayName: Ruleboards x-group: Ruleboards - name: ScansService description: View details of scans associated with projects in your organization. x-displayName: Scans x-group: Scans - name: ScmAppsService description: >- Manage connections to source code management systems (Github, Gitlab, etc.) x-displayName: Source Code Management (SCM) App x-group: Source Code Management (SCM) App - name: ScmService description: >- Manage connections to source code management systems (Github, Gitlab, etc.) x-displayName: Source Code Management (SCM) Configs x-group: Source Code Management (SCM) Configs - name: ScmSubscriptionsService description: Manage SCM Webhook Subscriptions x-displayName: Source Code Management (SCM) Webhooks x-group: Source Code Management (SCM) Webhooks - name: SlackService - name: SmsPackageManagerConfigService description: >- Manage authentication configurations for package managers used in Supply Chain Analysis (SCA) scans. x-displayName: Supply Chain - SMS Package Manager Configurations x-group: Supply Chain - SMS Package Manager Configurations - name: SmsScaResolutionConfigService description: >- Retrieve custom dependency resolution configurations for lockfileless scans. x-displayName: Supply Chain - SMS SCA Resolution Configurations x-group: Supply Chain - SMS SCA Resolution Configurations - name: SupplyChain2Service description: >- The Supply Chain is all of the dependencies of code, rather than the code itself. This service gives information about the supply chain. x-displayName: Supply Chain x-group: Supply Chain - name: SupportService description: Create and List Support Cases x-displayName: Support Service x-group: Support Service - name: SurveysService description: Retrieve and submit company surveys x-displayName: Surveys x-group: Surveys - name: TasksService description: >- Many tasks are done asynchronously; this service deals with managing async tasks. x-displayName: Tasks x-group: Tasks - name: TeamsService description: >- Teams are used to manage access control for resources within a deployment. For more information visit https://semgrep.dev/docs/deployment/teams. x-displayName: Teams x-group: Teams - name: TokenService description: >- Tokens are used for programmatic access to the Semgrep Cloud Platform APIs. x-displayName: Tokens x-group: Tokens - name: UsersService description: Manage user accounts, settings, and organization memberships x-displayName: Users Auth Service x-group: Users Auth Service - name: VersionsService description: Semgrep version information x-displayName: Versions x-group: Versions - name: WizCredentialService description: Manage Wiz credentials x-displayName: Wiz Credentials x-group: Wiz Credentials paths: /api/v2/deployments/{deploymentId}/projects/{projectId}/scans/list: post: tags: - ScansService summary: List Scans description: >- List the scans associated with a particular project from the past 30 days. operationId: ScansService_ListScans parameters: - name: deploymentId in: path required: true schema: example: '1234' title: Deployment ID type: string description: >- The unique numerical identifier of your deployment. Can be found via the [Deployments Service](#tag/DeploymentsService) or in your Settings in the web UI. format: int64 - name: projectId in: path required: true schema: example: '5678' title: Project ID type: string description: >- The unique numerical identifier for the project that was scanned. Can be found via the [Projects Service](#tag/ProjectsService), or in the Projects panel in the web UI. format: int64 requestBody: content: application/json: schema: $ref: '#/components/schemas/protos.scan.v2.ListScansRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/protos.scan.v2.ListScansResponse' security: - SemgrepWebToken: [] - SemgrepJWT: [] components: schemas: protos.scan.v2.ListScansRequest: type: object properties: cursor: type: string description: >- Include the cursor from the previous response to paginate through the results limit: example: 100 type: integer description: Number of scans to return per page. Default is 100, max is 500. format: int64 filters: $ref: '#/components/schemas/protos.scan.v2.ListScansFilters' protos.scan.v2.ListScansResponse: type: object properties: scans: type: array items: $ref: '#/components/schemas/protos.scan.v2.Scan' description: The list of scans. cursor: type: string description: Cursor to retrieve the next page of results. protos.scan.v2.ListScansFilters: title: List Scans Filter type: object properties: branch: example: refs/heads/main type: string description: >- Only get scans from the specified branch within your project. If not specified, scans from all branches will be returned. createdSince: example: '2019-08-24T14:15:22.000Z' type: string description: >- Only get scans created after this time. Provide time in ISO 8601 format. format: date-time duration: $ref: '#/components/schemas/protos.scan.v2.ScanDurationRange' includeEnabledProducts: example: - PRODUCT_SAST - PRODUCT_SECRETS enum: - PRODUCT_SAST - PRODUCT_SCA - PRODUCT_SECRETS - PRODUCT_AI_SAST type: array items: enum: - PRODUCT_UNSPECIFIED - PRODUCT_SAST - PRODUCT_SCA - PRODUCT_SECRETS - PRODUCT_AI_SAST type: string format: enum description: |+ Only get scans that include all of the specified products (or more). | value | description | |-------|---------------| | PRODUCT_SAST | | | PRODUCT_SCA | | | PRODUCT_SECRETS | | | PRODUCT_AI_SAST | | statuses: example: - SCAN_STATUS_RUNNING - SCAN_STATUS_COMPLETED enum: - SCAN_STATUS_RUNNING - SCAN_STATUS_COMPLETED - SCAN_STATUS_PENDING - SCAN_STATUS_CANCELLED - SCAN_STATUS_ERROR - SCAN_STATUS_NEVER_FINISHED type: array items: enum: - SCAN_STATUS_UNSPECIFIED - SCAN_STATUS_RUNNING - SCAN_STATUS_COMPLETED - SCAN_STATUS_PENDING - SCAN_STATUS_CANCELLED - SCAN_STATUS_ERROR - SCAN_STATUS_NEVER_FINISHED type: string format: enum description: >+ Only get scans that match one of these statuses. | value | description | |-------|---------------| | SCAN_STATUS_RUNNING | The scan is currently running | | SCAN_STATUS_COMPLETED | The scan has completed successfully (0 or 1 exit code) | | SCAN_STATUS_PENDING | The scan is queued and waiting to start | | SCAN_STATUS_CANCELLED | The scan was cancelled before completion | | SCAN_STATUS_ERROR | The scan has exited with a failure (exit code not 0 or 1) | | SCAN_STATUS_NEVER_FINISHED | The scan did not report an error or success after over an hour | types: example: - SCAN_TYPE_FULL enum: - SCAN_TYPE_FULL - SCAN_TYPE_DIFF type: array items: enum: - SCAN_TYPE_UNSPECIFIED - SCAN_TYPE_FULL - SCAN_TYPE_DIFF type: string format: enum description: >+ Only get scans matching one of the specified types. If not specified, scans of any type will be returned. | value | description | |-------|---------------| | SCAN_TYPE_FULL | [Full scan](https://semgrep.dev/docs/semgrep-code/glossary#full-scan) | | SCAN_TYPE_DIFF | [Diff-aware scan](https://semgrep.dev/docs/semgrep-code/glossary#diff-aware-scan) | description: >- Specify some or all of these optional filters to narrow down the results. protos.scan.v2.Scan: title: Scan type: object properties: id: example: '12345' title: Scan ID type: string description: The unique numerical identifier for the scan format: int64 deploymentId: example: '1605' type: string description: >- The unique numerical identifier of the deployment associated with the scanned project format: int64 projectId: example: '7884' type: string description: The unique numerical identifier for the project that was scanned format: int64 branchId: example: '7890' type: string description: >- The unique numerical identifier of the branch the scan was run on Get more details about the branch from [Get Branch](#tag/ProjectsService/operation/ProjectsService_GetBranch). format: int64 commit: example: abcdef1234567890 type: string description: The commit hash that the scan was run on startTime: example: '2023-11-18T23:28:12.391Z' type: string description: Timestamp of when the scan started format: date-time completeTime: example: '2023-11-18T23:30:12.391Z' type: string description: Timestamp of when the scan completed format: date-time exitCode: example: 0 type: string description: The exit code of the scan, can be negative isFullScan: example: true type: boolean description: Whether the scan is a full scan duration: example: 501.4 pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: >- The total time the scan took to run in seconds. Note that this does not include the time it took to upload the scan results. findingsCounts: $ref: '#/components/schemas/protos.scan.v2.ScanFindingsCounts' status: example: SCAN_STATUS_RUNNING enum: - SCAN_STATUS_RUNNING - SCAN_STATUS_COMPLETED - SCAN_STATUS_PENDING - SCAN_STATUS_CANCELLED - SCAN_STATUS_ERROR - SCAN_STATUS_NEVER_FINISHED type: string description: >+ Whether the scan is running, completed, or errored | value | description | |-------|---------------| | SCAN_STATUS_RUNNING | The scan is currently running | | SCAN_STATUS_COMPLETED | The scan has completed successfully (0 or 1 exit code) | | SCAN_STATUS_PENDING | The scan is queued and waiting to start | | SCAN_STATUS_CANCELLED | The scan was cancelled before completion | | SCAN_STATUS_ERROR | The scan has exited with a failure (exit code not 0 or 1) | | SCAN_STATUS_NEVER_FINISHED | The scan did not report an error or success after over an hour | format: enum enabledProducts: example: - PRODUCT_SAST - PRODUCT_SCA - PRODUCT_SECRETS enum: - PRODUCT_SAST - PRODUCT_SCA - PRODUCT_SECRETS - PRODUCT_AI_SAST type: array items: enum: - PRODUCT_UNSPECIFIED - PRODUCT_SAST - PRODUCT_SCA - PRODUCT_SECRETS - PRODUCT_AI_SAST type: string format: enum description: |+ The products used when running the scan. | value | description | |-------|---------------| | PRODUCT_SAST | | | PRODUCT_SCA | | | PRODUCT_SECRETS | | | PRODUCT_AI_SAST | | description: A scan of a project. protos.scan.v2.ScanDurationRange: title: Scan Duration Range type: object properties: min: example: 12.5 type: number description: >- The minimum duration of the scan in seconds. If not specified, the minimum duration will be 0. format: float max: example: 60 type: number description: >- The maximum duration of the scan in seconds. If not specified, the maximum duration will be infinity. format: float description: >- Only get scans that have a total running time (in seconds) within this range. protos.scan.v2.ScanFindingsCounts: title: Scan Findings Counts type: object properties: total: example: 10 type: integer description: The total number of findings in the scan format: int64 code: example: 5 type: integer description: The number of code findings in the scan format: int64 supplyChain: example: 3 type: integer description: The number of supply chain findings in the scan format: int64 secrets: example: 2 type: integer description: The number of secrets findings in the scan format: int64 description: The number of findings in a scan by product securitySchemes: SemgrepWebToken: type: http description: >- Get access to data with your API token. Example header: `Authorization: Bearer 2991e2fb4b540fe75b8f90677b0b892b6314e4961cb001fe6eb452eee248a628` The token can be provisioned from the Tokens section in your Settings, and requires explicitly enabling `Web API` access. scheme: bearer bearerFormat: string SemgrepJWT: type: http description: Get access to data with your user's JSON Web Token. scheme: bearer bearerFormat: string ````