> ## Documentation Index
> Fetch the complete documentation index at: https://chainpatrol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Blocked Threats by First-Report Source
> Count distinct currently blocked assets whose earliest report for the organization falls in the date range, split into customer vs ChainPatrol (staff + automation). Blocked is current status or pending BLOCKED, not blockedAt. This does not equal /metrics/found.
## Overview
Count the distinct currently blocked assets whose earliest report for your organization
falls in a date range, split by who reported them first: your team (`customer`) or
ChainPatrol (`chainpatrol`). Use this endpoint to see how many blocked threats were
discovered proactively by ChainPatrol versus submitted by your own team and community.
This endpoint is gated behind the `threat-discovery-source-api` feature flag on a
per-organization basis. If the flag is not enabled for your organization, the API
returns a 403 Forbidden error. Contact ChainPatrol to enable access.
## How assets are counted
* **First-report cohort** — Each asset is attributed to the source of its earliest
non-deleted report for your organization. The date range filters on when that first
report was created, not on when the asset was blocked.
* **Blocked only** — Only assets whose current status (or pending status) is `BLOCKED`
are counted. Assets that were reported in the range but never blocked, or later
unblocked, are excluded.
* **Source buckets**:
* `customer` — assets first reported by your team, an external reporter, or a
customer-role user.
* `chainpatrol` — assets first reported by ChainPatrol staff or automation. Staff
and automation are collapsed into a single bucket.
* `totals` — `customer` + `chainpatrol`.
`totals.blocked` does not match the counts from [`POST
/metrics/found`](/docs/external-api/metrics-found). This endpoint windows on each asset's
first report date, while `/metrics/found` counts assets by when they were blocked.
## Date handling
* `startDate` and `endDate` are required, and `startDate` must be on or before
`endDate`.
* Date-only values (`YYYY-MM-DD`) are interpreted in UTC. `startDate` begins at
midnight UTC and `endDate` covers the whole day (through 23:59:59.999 UTC). Pass a
full ISO 8601 timestamp for a precise cut-off.
* Impossible calendar dates (for example `2026-02-31`) are rejected with a 400 error
instead of being rolled forward to the next month.
## Brand filtering
Pass the optional `brandIds` array to restrict counts to assets belonging to specific
brands. Every ID must belong to your organization. If any ID references a brand outside
your organization (or a deleted brand), the API returns a 404 error instead of silently
ignoring it.
## Example request
```bash theme={null}
curl --request POST \
--url https://app.chainpatrol.io/api/v2/metrics/found-by-source \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--data '{
"slug": "your-org-slug",
"startDate": "2026-07-01",
"endDate": "2026-07-31",
"brandIds": [123]
}'
```
## Example response
```json theme={null}
{
"range": {
"startDate": "2026-07-01T00:00:00.000Z",
"endDate": "2026-07-31T23:59:59.999Z"
},
"customer": {
"blocked": 42
},
"chainpatrol": {
"blocked": 137
},
"totals": {
"blocked": 179
}
}
```
## OpenAPI
````yaml POST /metrics/found-by-source
openapi: 3.0.3
info:
title: ChainPatrol External API - OpenAPI 3.0
description: ChainPatrol External API documentation
version: 2.0.0
servers:
- url: https://app.chainpatrol.io/api/v2
security: []
tags:
- name: asset
- name: report
externalDocs:
url: https://chainpatrol.com/docs
paths:
/metrics/found-by-source:
post:
tags:
- metrics
summary: Get currently blocked threats by first-report source
description: >-
Count distinct currently blocked assets whose earliest report for the
organization falls in the date range, split into customer vs ChainPatrol
(staff + automation). Blocked is current status or pending BLOCKED, not
blockedAt. This does not equal /metrics/found.
operationId: metricsFoundBySource
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
slug:
type: string
minLength: 1
description: Organization slug
startDate:
type: string
description: >-
Only include assets whose earliest report was created on or
after this date. A date-only value (YYYY-MM-DD) starts at
midnight UTC
endDate:
type: string
description: >-
Only include assets whose earliest report was created on or
before this date. A date-only value (YYYY-MM-DD) covers the
whole day in UTC; pass a full timestamp for a precise
cut-off
brandIds:
type: array
items:
type: integer
minimum: 0
exclusiveMinimum: true
description: Only include assets belonging to these brands
required:
- slug
- startDate
- endDate
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
range:
type: object
properties:
startDate:
type: string
endDate:
type: string
required:
- startDate
- endDate
customer:
type: object
properties:
blocked:
type: integer
minimum: 0
description: >-
Distinct assets whose earliest report for this org
falls in the range and whose current status or pending
status is BLOCKED
required:
- blocked
description: >-
Currently blocked assets first reported by the customer
(reportedByCustomer, external reporter, or customer-role
user)
chainpatrol:
type: object
properties:
blocked:
type: integer
minimum: 0
description: >-
Distinct assets whose earliest report for this org
falls in the range and whose current status or pending
status is BLOCKED
required:
- blocked
description: >-
Currently blocked assets first reported by ChainPatrol
staff or automation. Staff and automation are collapsed
together.
totals:
type: object
properties:
blocked:
type: integer
minimum: 0
description: >-
Distinct assets whose earliest report for this org
falls in the range and whose current status or pending
status is BLOCKED
required:
- blocked
description: >-
customer + chainpatrol. This is a first-report blocked
cohort and does not equal metrics/found, which counts
assets by blockedAt.
required:
- range
- customer
- chainpatrol
- totals
'400':
description: Invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/error.BAD_REQUEST'
'401':
description: Authorization not provided
content:
application/json:
schema:
$ref: '#/components/schemas/error.UNAUTHORIZED'
'403':
description: Insufficient access
content:
application/json:
schema:
$ref: '#/components/schemas/error.FORBIDDEN'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
security:
- ApiKey: []
components:
schemas:
error.BAD_REQUEST:
type: object
properties:
message:
type: string
description: The error message
example: Invalid input data
code:
type: string
description: The error code
example: BAD_REQUEST
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Invalid input data error (400)
description: The error information
example:
code: BAD_REQUEST
message: Invalid input data
issues: []
error.UNAUTHORIZED:
type: object
properties:
message:
type: string
description: The error message
example: Authorization not provided
code:
type: string
description: The error code
example: UNAUTHORIZED
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Authorization not provided error (401)
description: The error information
example:
code: UNAUTHORIZED
message: Authorization not provided
issues: []
error.FORBIDDEN:
type: object
properties:
message:
type: string
description: The error message
example: Insufficient access
code:
type: string
description: The error code
example: FORBIDDEN
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Insufficient access error (403)
description: The error information
example:
code: FORBIDDEN
message: Insufficient access
issues: []
error.INTERNAL_SERVER_ERROR:
type: object
properties:
message:
type: string
description: The error message
example: Internal server error
code:
type: string
description: The error code
example: INTERNAL_SERVER_ERROR
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Internal server error error (500)
description: The error information
example:
code: INTERNAL_SERVER_ERROR
message: Internal server error
issues: []
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-KEY
description: >-
Your API key. This is required by most endpoints to access our API
programatically. Reach out to us at
[support@chainpatrol.io](mailto:support@chainpatrol.io?subject=Re:%20API%20Key%20for%20SDK&body=Company:%20%0AName:%20%0APurpose:%20)
to get an API key for your use.
````