> ## Documentation Index > Fetch the complete documentation index at: https://docs.range.org/llms.txt > Use this file to discover all available pages before exploring further. # List Screening History > List stored workspace assessments with pagination, address, severity, and date filters, including failed screens when requested. ## OpenAPI ````yaml get /v2/risk/history openapi: 3.0.0 info: title: Range Risk API description: The Range Risk API for risk assessment of crypto addresses. version: 1.7.37 contact: {} servers: - url: https://api.range.org description: Range API Server security: - Authorization: [] tags: - name: Risk description: Get risk information about a crypto address. - name: Risk v2 description: >- Address risk assessment, workspace configuration, and signals catalogue (API v2). - name: Simulator description: Simulate a transaction on a network. paths: /v2/risk/history: get: tags: - Risk v2 summary: List screening history description: >- Returns the most recent screening assessments for the workspace inferred from the API key. Use `limit` (1-100, default 10) for page size and `offset` to paginate. Pass `address` to restrict the page to screens requested for one address; `limit=1` then returns just the latest screening for it. Pass `severity` with one or more comma-separated severities to restrict the page to screens that scored one of them, and `sort=severity` to order the page worst-first instead of newest-first. Pass `from`/`to` to bound the page by screening time, and `include_failed=true` to also see screens that errored (each item then carries a `success` field). Unlike `GET /v2/risk/address`, this endpoint reads stored assessments and consumes **no screening credits**. Returns empty when the key has no associated workspace. operationId: getHistory parameters: - name: offset required: false in: query description: Number of records to skip. Defaults to 0. schema: type: string - name: limit required: false in: query description: Page size, 1-100 inclusive. Defaults to 10. schema: type: string - name: address required: false in: query description: >- Return only screens requested for this address. `metadata.total` reflects the filtered count. The value is normalised exactly as `GET /v2/risk/address` normalises it, so equivalent forms of the same address match the same records — note this can change the address by more than case (EVM addresses are lowercased; a Stellar muxed `M…` account folds to its base `G…` account), and the records returned echo the normalised form. Passing the parameter with an empty value is a client error, not an unfiltered request. schema: type: string - name: sort required: false in: query description: >- Page ordering. `newest` (default) is the assessment `timestamp` descending — the field returned on each item. `severity` orders worst-first, by severity rank rather than alphabetically, with newest as the tiebreak within a band; a screen with no recorded severity ranks alongside `none`, at the bottom. Both orders carry an internal tiebreak so paging is deterministic. `metadata.applied_sort` echoes the order used. An unrecognised value is a client error rather than a silent fallback to the default. schema: enum: - newest - severity type: string - name: from required: false in: query description: >- Only return screens queried at or after this ISO 8601 date-time (inclusive). A bare date (`2026-05-01`) or a date-time with no `Z`/offset (`2026-05-01T00:00:00`) is interpreted as UTC, not the server's local time; a value carrying `Z` or an explicit offset is honoured as given. `metadata.filtered_from` echoes the applied bound. An unparseable value is a client error, not an unfiltered request. schema: type: string - name: to required: false in: query description: >- Only return screens queried at or before this ISO 8601 date-time (inclusive). Parsed as UTC the same way as `from`, except a bare date (`2026-05-31`) expands to the inclusive end of that UTC day (`23:59:59.999Z`) rather than its start. `metadata.filtered_to` echoes the applied bound. An unparseable value is a client error, not an unfiltered request. schema: type: string - name: include_failed required: false in: query description: >- When `true` (or `1`), also include screens that failed (`success: false`) and set `success` on every item in the response. Defaults to `false`, which is this endpoint's original behaviour: only successful screens, and no `success` field on items. A failed item always reports `severity: 'none'` (no assessment ran), so combining this with `?severity=` excludes every failed screen — `metadata->>'severity'` is NULL for those rows, not `'none'`, and the severity filter only matches recorded values. schema: type: string - name: severity required: false in: query description: >- Return only screens whose overall severity is one of these. Comma-separated for more than one (`severity=high,severe`) or repeated (`severity=high&severity=severe`), case-insensitive, and duplicates are collapsed. This is **set membership, not a threshold** — `severity=high` returns high and nothing else, so a caller after "everything that needs review" must name each severity it wants (`severity=severe,high`). `metadata.total` reflects the filtered count and `metadata.filtered_severity` echoes the applied set. An unrecognised value is a client error, as is passing the parameter with an empty value — neither is treated as an unfiltered request. Note that a stored screen with no recorded severity matches no value at all, so the filter is not a partition of the workspace's history. schema: type: array items: type: string enum: - severe - high - medium - low - none responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/HistoryResponseDto' components: schemas: HistoryResponseDto: type: object properties: items: type: array items: $ref: '#/components/schemas/HistoryItemDto' metadata: $ref: '#/components/schemas/HistoryMetadataDto' required: - items - metadata HistoryItemDto: type: object properties: screen_id: type: string example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 address: type: string example: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28' address_active_on: example: - ethereum - polygon description: >- Networks this address has labelled activity on (from addresses.labels). type: array items: type: string total_incoming_usd: type: number example: 1842300.45 description: >- All-counterparty incoming USD volume (lifetime). 0 for unsupported networks. total_outgoing_usd: type: number example: 1798450.12 description: All-counterparty outgoing USD volume (lifetime). malicious_incoming_usd: type: number example: 184500 description: USD volume from counterparties tagged as malicious. malicious_outgoing_usd: type: number example: 92300 description: USD volume to counterparties tagged as malicious. severity: type: string example: high enum: - severe - high - medium - low - none description: >- Worst individual signal severity across all three pillars, unless severity_override is present. severity_override: description: >- Present only when Range lowered the severity: the address is on the Range whitelist and carries no risk category of its own. Signals are reported unchanged. allOf: - $ref: '#/components/schemas/SeverityOverrideDto' attribution: $ref: '#/components/schemas/AttributionSummaryDto' exposure: $ref: '#/components/schemas/ExposureSummaryDto' behaviour: $ref: '#/components/schemas/BehaviourSummaryDto' timestamp: type: string example: '2026-05-04T14:30:00Z' evidence: type: object description: >- Present only when `include_evidence=true`. Same shape as GET /v2/risk/evidence/:screenId minus the wrapping screen_id. success: type: boolean example: true description: >- Whether this screen completed successfully. Present only when the request passed `include_failed=true`; a failed item still reports `severity`/`attribution`/`exposure`/`behaviour`/`meta` as empty placeholders rather than a real assessment. required: - screen_id - address - address_active_on - total_incoming_usd - total_outgoing_usd - malicious_incoming_usd - malicious_outgoing_usd - severity - attribution - exposure - behaviour - timestamp HistoryMetadataDto: type: object properties: limit: type: number example: 10 description: Page size (fixed at 10). offset: type: number example: 0 total: type: number example: 1234 description: >- Total screenings for this workspace matching the applied filters (successful only by default; includes failed screens when `include_failed=true`). filtered_address: type: string example: '0x742d35cc6634c0532925a3b844bc9e7595f2bd28' description: >- The normalised address the `address` filter matched on, echoed back so a caller can verify a returned item without re-deriving its own normalisation. Omitted when no `address` filter was supplied. filtered_severity: type: array example: - severe - high description: >- The severities the `severity` filter matched on, echoed back so a caller can confirm which filter produced this page. Lower-cased and deduplicated. Omitted when no `severity` filter was supplied. items: type: string enum: - severe - high - medium - low - none applied_sort: type: string example: newest enum: - newest - severity description: >- The ordering actually applied to this page. `newest` is the assessment `timestamp` descending; `severity` is severity descending with newest as the tiebreak. Always returned by `GET /v2/risk/history`, so its absence there means the backend predates the parameter. Not returned by `GET /v2/risk/scans`, which has no `sort` parameter. filtered_from: type: string example: '2026-05-01T00:00:00.000Z' description: >- The `from` bound the request filtered on (ISO 8601), echoed back. Omitted when no `from` filter was supplied. filtered_to: type: string example: '2026-05-31T23:59:59.000Z' description: >- The `to` bound the request filtered on (ISO 8601), echoed back. Omitted when no `to` filter was supplied. required: - limit - offset - total SeverityOverrideDto: type: object properties: type: type: string example: range_whitelist enum: - range_whitelist original_severity: type: string example: severe enum: - severe - high - medium - low - none description: The severity the signals computed before the override. criterion: type: string example: uncontrollable_infrastructure enum: - trusted_entity - uncontrollable_infrastructure reason: type: string example: Cross-chain router; inbound flows are permissionless whitelisted_at: type: string example: '2026-10-22T10:00:00.000Z' required: - type - original_severity - criterion - reason - whitelisted_at AttributionSummaryDto: type: object properties: triggered: type: array items: $ref: '#/components/schemas/AttributionSignalResultDto' required: - triggered ExposureSummaryDto: type: object properties: triggered: type: array items: $ref: '#/components/schemas/ExposureSignalResultDto' required: - triggered BehaviourSummaryDto: type: object properties: detected: type: array items: $ref: '#/components/schemas/BehaviourSignalResultDto' required: - detected AttributionSignalResultDto: type: object properties: signal: type: string example: sanctions_ofac severity: type: string example: severe enum: - severe - high - medium - low result: type: boolean example: true required: - signal - severity - result ExposureSignalResultDto: type: object properties: signal: type: string example: compliance-risk mode: type: string example: percentage enum: - percentage result: type: boolean example: true percentage: type: string example: 42.30% description: >- Exposed bucket volume as a share of total counterparty volume, formatted human-readable. summary: type: string example: >- 42.30% of counterparty volume is compliance-risk, crossing the 5% (high) threshold. description: Human-readable explanation of why this signal fired. required: - signal - mode - result - percentage - summary BehaviourSignalResultDto: type: object properties: behaviour: type: string example: smurfing severity: type: string example: high enum: - severe - high - medium - low confidence: type: number example: 0.78 minimum: 0 maximum: 1 ignored: type: boolean example: true description: >- True when the workspace set this behaviour to detect-only. Reported for visibility and excluded from the screen severity. required: - behaviour - severity - confidence securitySchemes: Authorization: type: apiKey in: header name: X-API-KEY description: Authorization method required to allow user to access the api endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.