Endpoint Pagination

The following endpoints in the Mandiant Advantage Threat Intelligence (MATI) API v4 support pagination for responses that contain a large amount of data.

Get Indicators (GET /v4/indicator): Returns a list of indicators based on parameters defined in the request.
List Reports (GET /v4/reports): Returns a list of finished intelligence reports created by Mandiant.
Search (POST /v4/search): Returns intelligence matching a defined query, including Threat Actors, Malware Families, Indicators, Vulnerabilities, and finished intelligence reports.
List Vulnerabilities (GET /v4/vulnerability): Returns a list of Vulnerabilities tracked by Mandiant.

By default, responses for these endpoints are paginated to include only 25 matching results at a time. The limit parameter lets you define the maximum number of results per page, with a limit of 1000 results per request. If the query matches more entities than what's displayed on the first response page, the response automatically includes a next token.

For example, the following Get Indicators query returns 25 indicators based on the epoch timestamp, along with a next token:

curl -X GET "https://api.intelligence.mandiant.com/v4/indicator?start_epoch=1693671421" -u YOUR_API_KEY_ID:YOUR_API_SECRET -H "Accept: application/json"

To get the next page of query results, the value of the next token should be used as the only parameter in the subsequent request. For example:

curl -X GET "https://api.intelligence.mandiant.com/v4/indicator?next=YOUR_NEXT_TOKEN" -u YOUR_API_KEY_ID:YOUR_API_SECRET -H "Accept: application/json"

The next token to be included in each subsequent query (to replace YOUR_PAGE_TOKEN in the previous curl command) is an encoded string of over 3000 characters.

A new next token is included in each paginated response. In order to obtain all matching results in the query response, you'll need to continue this process of updating the next token for each subsequent query. When the next token is not included in the response, or the server returns a 204 response code, there are no more results to return from the endpoint.

Pagination in web-based API clients

The following is an example workflow for executing this paginated query using the Postman API client web application.

Create a new workspace in Postman to configure the previous Get Indicators example query.
1. Navigate to https://web.postman.co/workspaces.
2. If you don't have an existing workspace, click Create Workspace.
3. Select Blank workspace and click Next.
4. At a minimum, enter a Name for the workspace and click Create.
5. Click  Add to open a new workspace tab.
Create the initial query to retrieve the first 25 indicators based on the epoch timestamp.
1. Select GET from the method drop-down and enter the base URL https://api.intelligence.mandiant.com/v4/indicator.
2. Navigate to the Params tab.
3. Enter start_epoch in the Key field and an epoch timestamp in the Value field.
  If you want to increase the number of results per page, enter limit in the Key field and the maximum number of results per page (up to 1000) in the Value field.
  The Params tab in Postman
4. Navigate to the Authorization tab and select Basic Auth from the Type drop-down.
5. Enter your YOUR_API_KEY_ID in the Username field and your YOUR_API_SECRET in the Password field.The Authorization tab in Postman
  1. For security reasons, save the values for your YOUR_API_KEY_ID and your YOUR_API_SECRET as variables in the Postman web console:
    1. Right-click the pasted value of your YOUR_API_KEY_ID or your YOUR_API_SECRET and click Set as variable.Set as variable modal
    2. If you haven't already set the value as a variable, click Set as new variable.Set as new variable modal
    3. Enter a Name for the variable.
    4. Select Global from the Scope drop-down.
    5. Click Set Variable.Set Variable modal
6. Navigate to the Headers tab.
7. Enter -H in the Key field and Accept: application/json in the Value field.
8. Click Send.The Headers tab in Postman
9. The last line of the response body includes the next token inside double quotes. Copy that token (without the quotes) for use in the subsequent query.The next token in the API response
Create the subsequent query to retrieve the next set of indicators.
1. Click  Add to open a new workspace tab for the next paginated query.
2. Select GET from the method drop-down and enter the base URL https://api.intelligence.mandiant.com/v4/indicator.
3. Select the Params tab.
4. Enter next in the Key field and the next token from the previous query in the Value field.
  For this and all other subsequent queries, no other parameters should be included besides the next parameter.
  The next token parameter used to query the subsequent page of results
5. Navigate to the Authorization tab and select Basic Auth from the Type drop-down.
6. Enter the variables for your YOUR_API_KEY_ID in the Username field and your YOUR_API_SECRET in the Password field.
7. Navigate to the Headers tab.
8. Enter -H in the Key field and Accept: application/json in the Value field.
9. Click Send.
Repeat this process until you no longer receive the next token in your response, or you receive a Status of 204 No Content, indicating that no more results are available.Status of 204 No Content indicates that no additional results are available