How to paginate responses from the Semgrep API

Semgrep's API endpoints use both offset-based pagination and cursor-based pagination.

Offset-based pagination

Offset-based pagination defines a limit to specify the number of entries fetched and offset to indicate where to start collecting data, which correspond to the page_size and page query parameters described in this section.

The following API endpoints support offset-based pagination:

• List all projects
• List code or supply chain findings

For these endpoints, include the following query parameters to paginate through results:

Query parameter	Type	Description
page	integer	The page of results to return. Page numbering begins at 0. Default: 0
page_size	integer	The maximum number of records returned per page. Default: 100.

Example

To request a list of Code or Supply Chain findings, specifically the second page where each page contains 100 items, make a cURL call as follows:

curl 'https://semgrep.dev/api/v1/deployments/docs_test/findings?page=2&page_size=100' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Cursor-based pagination

The List Secrets endpoint supports cursor-based pagination:

For these endpoints, include the following query parameters to paginate through results.

Query parameter	Type	Description
cursor	string	Cursor to paginate through the results. Provide the cursor value from the response to retrieve the next or previous page.
limit	integer	Page size to paginate through the results.

Example

To request a list of Secrets, make a cURL call as follows:

# modify the limit value to change the page size
curl 'https://semgrep.dev/api/v1/deployments/20169/secrets?cursor=&limit=25' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

The response includes the cursor attribute. Save the value returned with cursor, and provide it in subsequent calls to retrieve additional pages:

curl 'https://semgrep.dev/api/v1/deployments/20169/secrets?cursor=Pm...3D&limit=25' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Repeat this process for additional pages.

Mixed pagination

The following API endpoints support mixed usages of page- and cursor-based pagination:

• List supply chain vulnerabilities
• List repositories with dependencies
• List lockfiles in a given repository with dependencies
• List dependencies

Example

To request a list of Supply Chain vulnerabilities, make a call to the following URL. Adjust page_size accordingly:

curl 'https://semgrep.dev/api/v1/deployments/20169/ssc-vulns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
    "page_size": 5
}'

The API returns, as part of the response, a cursor object that includes the vulnOffset and issueOffset keys:

{
    ...
    "cursor": {
        "vulnOffset": "4",
        "issueOffset": "60544963"
    }
}

Add the cursor object to the JSON body of subsequent calls to obtain additional pages:

curl 'https://semgrep.dev/api/v1/deployments/20169/ssc-vulns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
    "page_size": 5,
    "cursor": {
        "vulnOffset": "4",
        "issueOffset": "60544963"
    }
}'