Retrieve New Findings

This article provides an example demonstrating how to query for recent findings using the BQL API. While this example focuses on a specific set of attributes, you can tailor the query to include the attributes that fit your needs. For more details on the BQL API, see the BQL API documentation.

Start the query

Send a POST request to start the query. This example retrieves findings younger than 30 days with selected fields and a nested relationship projection for the vulnerability type.

curl -X POST 'https://<your-brinqa-instance>/v1/api/bql' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey <your-api-token>' \
  -d '{
    "query": "FIND Finding WHERE ageInDays < 30",
    "returningFields": ["id", "connectorNames", "firstFound", "riskRating", "statusCategory", "type(name, openFindingCount, patchAvailable, recommendation)"],
    "limit": 10
  }'

note

Replace <your-brinqa-instance> with the URL of your Brinqa Platform and <your-api-token> with your API token.

The API returns a 202 Accepted response with a Location header:

HTTP/2 202
Location: /v1/api/bql/eyJqb2JI...
Retry-After: 2

Fetch results

Use the Location value from the previous response to poll for results:

curl 'https://<your-brinqa-instance>/v1/api/bql/eyJqb2JI...' \
  -H 'Authorization: ApiKey <your-api-token>'

If the query is still processing, the response has status "processing". Poll again after the number of seconds indicated in the Retry-After header. When the query completes, the response contains the matching findings. Note how the type relationship is returned as a nested object:

{
  "status": "completed",
  "state": "success",
  "message": "Query completed successfully.",
  "results": [
    {
      "id": 1688658462571626517,
      "connectorNames": ["Qualys Vulnerability Management"],
      "firstFound": "2025-03-15T18:05:32Z",
      "riskRating": "Medium",
      "statusCategory": "Open",
      "type": {
        "name": "OpenSSH GSSAPI Credential Disclosure Vulnerability",
        "openFindingCount": 8,
        "patchAvailable": true,
        "recommendation": "This issue affects versions of OpenSSH prior to 4.2. The vendor released OpenSSH version 4.2 to address this issue."
      }
    },
    {
      "id": 1687513571912466447,
      "connectorNames": ["Brinqa Connect", "Brinqa Manual Entry"],
      "firstFound": "2025-03-22T00:00:00Z",
      "riskRating": "Low",
      "statusCategory": "Closed",
      "type": null
    }
  ],
  "totalRows": 2,
  "pageRows": 2,
  "cursor": null
}