> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search History

> Retrieve historical Minerva screening requests for audit and reconciliation workflows.

Use the search history endpoint to retrieve screening/search request metadata
that was created in Minerva for your tenant. This endpoint is intended for
audit-purpose search history retrieval: it helps compliance teams reconcile
which screenings were run, when they were run, who ran them when that user
context is available, and which submitted entities and feeds were included.

<Info>
  Search history retrieval is read-only. It does not submit a new screening,
  change review status, or modify historical records.
</Info>

## Endpoint

```http theme={null}
GET https://api.gominerva.com/v2/search/requests
```

Authenticate with the same API key header used by the other Minerva API
endpoints:

```bash theme={null}
x-api-key: YOUR_API_KEY
```

The API key determines the tenant whose historical requests are returned. API
keys are managed from <strong>Administration</strong> >

<strong>Developers</strong> in the Minerva dashboard.

## Query Parameters

| Parameter         | Description                                                                     |
| ----------------- | ------------------------------------------------------------------------------- |
| `page`            | One-based page number. Defaults to `1`.                                         |
| `limit`           | Number of requests to return per page. Defaults to `10` and is capped at `250`. |
| `q`               | Optional case-insensitive search against submitted entity names.                |
| `job_id`          | Optional search job identifier to retrieve requests from a specific job.        |
| `created_at_from` | Inclusive lower bound for the request creation time.                            |
| `created_at_to`   | Inclusive upper bound for the request creation time.                            |
| `sort_key`        | Sort field. Only `created_at` is currently supported.                           |
| `sort`            | Sort direction: `desc` or `asc`. Defaults to `desc`.                            |

<Tip>
  Use RFC3339 date-time values with an explicit timezone, such as
  <code>2026-05-01T00:00:00Z</code>. When building URLs, use your HTTP client's
  query parameter encoder, <code>URLSearchParams</code>, or
  <code>--data-urlencode</code> so reserved characters such as
  <code>:</code> and <code>+</code> are encoded safely.
</Tip>

## List Recent Search Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.gominerva.com/v2/search/requests" \
    -H "x-api-key: YOUR_API_KEY" \
    --data-urlencode "limit=25" \
    --data-urlencode "sort=desc"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    limit: "25",
    sort: "desc",
  });

  const response = await fetch(
    `https://api.gominerva.com/v2/search/requests?${params}`,
    {
      headers: {
        "x-api-key": process.env.MINERVA_API_KEY,
      },
    },
  );

  if (!response.ok) {
    throw new Error(`Minerva API returned ${response.status}`);
  }

  const data = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://api.gominerva.com/v2/search/requests",
      headers={"x-api-key": os.environ["MINERVA_API_KEY"]},
      params={"limit": 25, "sort": "desc"},
      timeout=30,
  )
  response.raise_for_status()

  data = response.json()
  ```
</CodeGroup>

## Retrieve A Date Range

Date range filters are inclusive and apply to the request's

<code>created\_at</code> timestamp.

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.gominerva.com/v2/search/requests" \
    -H "x-api-key: YOUR_API_KEY" \
    --data-urlencode "created_at_from=2026-05-01T00:00:00Z" \
    --data-urlencode "created_at_to=2026-05-31T23:59:59Z" \
    --data-urlencode "limit=100" \
    --data-urlencode "sort=asc"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    created_at_from: "2026-05-01T00:00:00Z",
    created_at_to: "2026-05-31T23:59:59Z",
    limit: "100",
    sort: "asc",
  });

  const response = await fetch(
    `https://api.gominerva.com/v2/search/requests?${params}`,
    {
      headers: {
        "x-api-key": process.env.MINERVA_API_KEY,
      },
    },
  );

  if (!response.ok) {
    throw new Error(`Minerva API returned ${response.status}`);
  }

  const data = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://api.gominerva.com/v2/search/requests",
      headers={"x-api-key": os.environ["MINERVA_API_KEY"]},
      params={
          "created_at_from": "2026-05-01T00:00:00Z",
          "created_at_to": "2026-05-31T23:59:59Z",
          "limit": 100,
          "sort": "asc",
      },
      timeout=30,
  )
  response.raise_for_status()

  data = response.json()
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "pagination": {
    "page": 1,
    "limit": 2,
    "total_count": 42,
    "total_pages": 21,
    "has_next": true,
    "has_prev": false
  },
  "requests": [
    {
      "id": "665f0d4c2d2f7c2b2f2f2f2f",
      "legacy_search_id": "legacy-search-123",
      "tenant_id": "org_123",
      "config": {
        "feeds": ["Sanctions", "PEP"]
      },
      "entities": [
        {
          "type": "individual",
          "name": "Jane Doe",
          "feeds": ["Sanctions", "PEP"],
          "custom_id": "case-1001"
        }
      ],
      "created_at": "2026-05-14T13:22:45Z",
      "updated_at": "2026-05-14T13:22:48Z",
      "user_id": "user_123",
      "user_name": "Compliance Analyst",
      "user_email": "analyst@example.com",
      "job_id": "665f0d4c2d2f7c2b2f2f2f30"
    }
  ]
}
```

## Paginating An Audit Export

For a full audit export, request pages until

<code>pagination.has\_next</code> is <code>false</code>. Keep the same filters on
each page so the result set remains consistent.

```javascript JavaScript theme={null}
let page = 1;
let hasNext = true;
const allRequests = [];

while (hasNext) {
  const params = new URLSearchParams({
    created_at_from: "2026-05-01T00:00:00Z",
    created_at_to: "2026-05-31T23:59:59Z",
    limit: "250",
    page: String(page),
  });

  const response = await fetch(
    `https://api.gominerva.com/v2/search/requests?${params}`,
    { headers: { "x-api-key": process.env.MINERVA_API_KEY } },
  );

  if (!response.ok) {
    throw new Error(`Minerva API returned ${response.status}`);
  }

  const data = await response.json();
  allRequests.push(...data.requests);
  hasNext = data.pagination.has_next;
  page += 1;
}
```

## Retrieving Associated Results

The search history response gives you the request metadata and the request
identifier. When you need the stored match-level results for a historical
request, use the returned <code>id</code> as the <code>request\_id</code> on the
search matches endpoint.

```bash cURL theme={null}
curl -G "https://api.gominerva.com/v2/search/matches" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "request_id=665f0d4c2d2f7c2b2f2f2f2f" \
  --data-urlencode "limit=100"
```