Skip to main content

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:

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

Query parameterTypeDescription
pageintegerThe page of results to return. Page numbering begins at 0. Default: 0
page_sizeintegerThe 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/YOUR_DEPLOYMENT_SLUG/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 parameterTypeDescription
cursorstringCursor to paginate through the results. Provide the cursor value from the response to retrieve the next or previous page.
limitintegerPage 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/YOUR_DEPLOYMENT_ID/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:

Example​

To request a list of repositories with dependencies, make a call to the following URL. Adjust page_size accordingly:

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

The API returns cursor as part of the response:

{
    ...
    "cursor": 1097374
}

Add the cursor key-value pair to the JSON body of subsequent calls to obtain additional pages:

curl 'https://semgrep.dev/api/v1/deployments/YOUR_DEPLOYMENT_ID/dependencies/repositories' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
    "page_size": 1,
    "cursor": 1097374
}'

Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.