> ## Documentation Index
> Fetch the complete documentation index at: https://chainpatrol-mintlify-04a0fc55.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# List Organization Reports
> Answers 'which of my organization's reports match these filters?'. Returns full report records — proposals, assets, scans, reporter, SLA — with filtering and pagination, newest first. The organization comes from your API key, or pass `slug` when your credentials can reach more than one. To check whether a report already exists for specific assets before filing a new one, use `POST /reports/search`, which looks reports up by asset content in a single batched call.
## Overview
Retrieve security reports for your organization. This endpoint returns all reports submitted for your organization, including details about reported assets, proposals, and their current status. The organization is automatically inferred from your API key.
## Quick Start
### Authentication
Include your API key in the `X-API-KEY` header:
```bash theme={null}
X-API-KEY: your_api_key_here
```
### Example Request
```typescript TypeScript theme={null}
const response = await fetch(
"https://app.chainpatrol.io/api/v2/organization/reports?limit=50",
{
method: "GET",
headers: {
"X-API-KEY": "YOUR_API_KEY_HERE",
},
}
);
const data = await response.json();
console.log(data.reports);
```
```javascript JavaScript theme={null}
const response = await fetch(
"https://app.chainpatrol.io/api/v2/organization/reports?limit=50",
{
method: "GET",
headers: {
"X-API-KEY": "YOUR_API_KEY_HERE",
},
}
);
const data = await response.json();
console.log(data.reports);
```
```python Python theme={null}
import requests
response = requests.get(
"https://app.chainpatrol.io/api/v2/organization/reports",
headers={
"X-API-KEY": "YOUR_API_KEY_HERE",
},
params={
"limit": 50,
},
)
data = response.json()
print(data["reports"])
```
```bash cURL theme={null}
curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?limit=50' \
-H 'X-API-KEY: YOUR_API_KEY_HERE'
```
## Query Parameters
| Parameter | Type | Required | Description |
| ------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit | number | No | Number of reports to return per page (1-100, default: 50) |
| cursor | string | No | Cursor for pagination. Pass the cursor from the previous response to get the next page. |
| startDate | string | No | Filter reports created after this date (ISO 8601 format) |
| endDate | string | No | Filter reports created before this date (ISO 8601 format) |
| onlyRejected | boolean | No | If true, only return reports with rejected proposals (default: false) |
| reporterKind | string | No | Filter by the reporter (submitter). One of `human` or `automation`. |
| reviewerKind | string | No | Filter by the reviewer that approved the report. One of `human` or `automation`. |
| needsCustomerReview | boolean | No | If true, only return reports the organization still has to action (matches the Review page). If false, exclude them. |
| slug | string | No | Organization slug. Optional for organization-scoped API keys, which resolve the organization from the key. Required when your credentials can access more than one organization. |
The legacy `excludeAutomation` boolean is deprecated and kept as a backward-compatible alias for `reporterKind=human`. Prefer `reporterKind` in new integrations.
## Response
### Success Response
```json theme={null}
{
"reports": [
{
"id": "rpt_1234567890abcdef",
"createdAt": "2024-01-15T10:30:00.000Z",
"status": "APPROVED",
"assets": [
{
"id": 12345,
"content": "https://scam-site.com",
"type": "URL",
"status": "BLOCKED"
}
],
"proposals": [
{
"id": "prop_abc123",
"status": "APPROVED",
"reason": "phishing",
"createdAt": "2024-01-15T10:30:00.000Z"
}
]
}
],
"cursor": "next_page_cursor_string"
}
```
### Response Fields
| Field | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------------ |
| reports | array | Array of report objects for your organization |
| reports\[].id | string | Unique identifier for the report |
| reports\[].createdAt | string | ISO 8601 timestamp when the report was created |
| reports\[].status | string | Overall status of the report (PENDING, APPROVED, REJECTED) |
| reports\[].assets | array | Array of assets included in the report |
| reports\[].proposals | array | Array of proposals associated with the report |
| cursor | string | Cursor for the next page of results (undefined if no more results) |
## Pagination
Use the cursor-based pagination to fetch all reports:
```typescript TypeScript theme={null}
async function fetchAllReports() {
let allReports = [];
let cursor: string | undefined = undefined;
while (true) {
const params = new URLSearchParams({
limit: "100",
...(cursor && { cursor }),
});
const response = await fetch(
`https://app.chainpatrol.io/api/v2/organization/reports?${params}`,
{
method: "GET",
headers: {
"X-API-KEY": "YOUR_API_KEY_HERE",
},
}
);
const data = await response.json();
allReports = allReports.concat(data.reports);
cursor = data.cursor;
if (!cursor) {
break;
}
}
return allReports;
}
fetchAllReports()
.then((reports) => console.log(`Total reports: ${reports.length}`))
.catch((error) => console.error("Error:", error));
```
```python Python theme={null}
import requests
def fetch_all_reports():
all_reports = []
cursor = None
while True:
params = {"limit": 100}
if cursor:
params["cursor"] = cursor
response = requests.get(
"https://app.chainpatrol.io/api/v2/organization/reports",
headers={"X-API-KEY": "YOUR_API_KEY_HERE"},
params=params,
)
data = response.json()
all_reports.extend(data["reports"])
cursor = data.get("cursor")
if not cursor:
break
return all_reports
try:
reports = fetch_all_reports()
print(f"Total reports: {len(reports)}")
except Exception as error:
print(f"Error: {str(error)}")
```
## Filtering Examples
### Filter by Date Range
Get reports from a specific time period:
```bash theme={null}
curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?startDate=2024-01-01T00:00:00Z&endDate=2024-03-31T23:59:59Z' \
-H 'X-API-KEY: YOUR_API_KEY_HERE'
```
### Filter Only Rejected Reports
Get reports that have rejected proposals:
```bash theme={null}
curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?onlyRejected=true' \
-H 'X-API-KEY: YOUR_API_KEY_HERE'
```
### Combine Filters
Get rejected reports from a specific date range:
```bash theme={null}
curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?startDate=2024-01-01T00:00:00Z&endDate=2024-03-31T23:59:59Z&onlyRejected=true&limit=100' \
-H 'X-API-KEY: YOUR_API_KEY_HERE'
```
### Filter by Reporter or Reviewer
Use `reporterKind` and `reviewerKind` to separate reports submitted or approved by human users from those handled by ChainPatrol Automation. This is useful for measuring automation performance or exporting only human-driven activity.
Get only reports submitted by human reporters:
```bash theme={null}
curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?reporterKind=human' \
-H 'X-API-KEY: YOUR_API_KEY_HERE'
```
Get reports that were approved by ChainPatrol Automation:
```bash theme={null}
curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?reviewerKind=automation' \
-H 'X-API-KEY: YOUR_API_KEY_HERE'
```
### Filter to Reports Waiting on Customer Approval
Use `needsCustomerReview=true` to return only reports the organization still has to action — the same queue the organization's Review page shows. This is useful for building a "reports needing your review" dashboard or exporting the current approval backlog. Pass `false` to return only reports that are not waiting on the organization.
A report counts when it has at least one pending proposal that is the organization's to action:
* A proposal that ChainPatrol staff escalated to the organization and the organization has not answered yet, or
* Any pending proposal on a report the organization submitted itself.
Obligatory Organization Admin Approval does not widen this filter — an untriaged proposal is still ChainPatrol's to review, and only reaches the organization once staff escalate it.
```bash theme={null}
curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?needsCustomerReview=true' \
-H 'X-API-KEY: YOUR_API_KEY_HERE'
```
## Error Responses
### 401 Unauthorized
Returned when the API key is missing, invalid, or doesn't have organization access:
```json theme={null}
{
"error": {
"code": "UNAUTHORIZED",
"message": "API key with organization access required"
}
}
```
### 400 Bad Request
Returned when query parameters are invalid:
```json theme={null}
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid date format. Use ISO 8601 format."
}
}
```
## Use Cases
### Monitor Recent Reports
```typescript theme={null}
async function getRecentReports(days: number = 7) {
const startDate = new Date();
startDate.setDate(startDate.getDate() - days);
const response = await fetch(
`https://app.chainpatrol.io/api/v2/organization/reports?startDate=${startDate.toISOString()}&limit=100`,
{
headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
}
);
const { reports } = await response.json();
console.log(`Found ${reports.length} reports in the last ${days} days`);
return reports;
}
```
### Track Rejected Reports
```typescript theme={null}
async function analyzeRejectedReports() {
const response = await fetch(
"https://app.chainpatrol.io/api/v2/organization/reports?onlyRejected=true",
{
headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
}
);
const { reports } = await response.json();
// Analyze rejection reasons
const rejectionReasons = reports.flatMap((report) =>
report.proposals
.filter((p) => p.status === "REJECTED")
.map((p) => p.rejectionReason)
);
console.log("Common rejection reasons:", rejectionReasons);
return rejectionReasons;
}
```
### Export Reports to CSV
```typescript theme={null}
async function exportReportsToCSV(startDate: string, endDate: string) {
const response = await fetch(
`https://app.chainpatrol.io/api/v2/organization/reports?startDate=${startDate}&endDate=${endDate}&limit=100`,
{
headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
}
);
const { reports } = await response.json();
const csvHeader = "Report ID,Created At,Status,Assets,Proposals\n";
const csvRows = reports
.map(
(r) =>
`${r.id},${r.createdAt},${r.status},${r.assets.length},${r.proposals.length}`
)
.join("\n");
const csv = csvHeader + csvRows;
// Save or return CSV
return csv;
}
```
## Best Practices
### Pagination
* Use `limit=100` for bulk data retrieval to minimize API calls
* Always check for the `cursor` field to determine if more results exist
* Store the cursor if you need to resume pagination later
### Date Filtering
* Always use ISO 8601 format for dates: `YYYY-MM-DDTHH:mm:ss.sssZ`
* Include timezone information (typically UTC with `Z` suffix)
* Use both `startDate` and `endDate` for precise time ranges
### Performance
* Cache report data when appropriate to reduce API calls
* Use date filters to limit the result set size
* Consider polling intervals if monitoring for new reports (5-10 minutes recommended)
## Notes
* Organization is automatically determined from your API key
* All timestamps are in ISO 8601 format with UTC timezone
* The `onlyRejected` filter shows reports with at least one rejected proposal, but the report may contain other approved proposals
* Reports are ordered by creation date (newest first)
* The cursor is opaque and should not be parsed or modified
## OpenAPI
````yaml GET /organization/reports
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:
/organization/reports:
get:
tags:
- organization
summary: List organization reports
description: >-
Answers 'which of my organization's reports match these filters?'.
Returns full report records — proposals, assets, scans, reporter, SLA —
with filtering and pagination, newest first. The organization comes from
your API key, or pass `slug` when your credentials can reach more than
one. To check whether a report already exists for specific assets before
filing a new one, use `POST /reports/search`, which looks reports up by
asset content in a single batched call.
operationId: organizationReportsList
parameters:
- in: query
name: limit
schema:
type: number
minimum: 1
maximum: 20
required: true
- in: query
name: cursor
schema:
type: number
nullable: true
- in: query
name: status
schema:
type: string
enum:
- TODO
- IN_PROGRESS
- CLOSED
- in: query
name: searchQuery
schema:
type: string
- in: query
name: reporterQuery
schema:
type: string
- in: query
name: reporterKind
schema:
type: string
enum:
- human
- automation
- in: query
name: reviewerKind
schema:
type: string
enum:
- human
- automation
- in: query
name: reviewedByUserId
schema:
type: number
nullable: true
- in: query
name: startDate
schema:
type: string
- in: query
name: endDate
schema:
type: string
- in: query
name: updatedAtStartDate
schema:
type: string
- in: query
name: updatedAtEndDate
schema:
type: string
- in: query
name: registrars
schema:
type: array
items:
type: string
- in: query
name: hasMxRecords
schema:
type: boolean
- in: query
name: slug
schema:
type: string
- in: query
name: excludeAutomation
schema:
type: boolean
default: false
- in: query
name: onlyRejected
schema:
type: boolean
default: false
- in: query
name: onlyFavorited
schema:
type: boolean
default: false
- in: query
name: reportedByCustomer
schema:
type: boolean
- in: query
name: needsCustomerReview
schema:
type: boolean
- in: query
name: reviewStatuses
schema:
type: array
items:
type: string
enum:
- APPROVE
- REJECT
- SKIP
- ESCALATE
- in: query
name: assetTypes
schema:
type: array
items:
type: string
enum:
- URL
- PAGE
- ADDRESS
- DISCORD
- LINKEDIN
- TWITTER
- FACEBOOK
- YOUTUBE
- REDDIT
- TELEGRAM
- GOOGLE_APP_STORE
- APPLE_APP_STORE
- AMAZON_APP_STORE
- MICROSOFT_APP_STORE
- TIKTOK
- INSTAGRAM
- THREADS
- MEDIUM
- CHROME_WEB_STORE
- MOZILLA_ADDONS
- OPERA_ADDONS
- EMAIL
- PATREON
- OPENSEA
- FARCASTER
- IPFS
- GOOGLE_FORM
- WHATSAPP
- DISCORD_USER
- QUORA
- GITHUB
- TEACHABLE
- SUBSTACK
- DEBANK
- TAWK_TO
- JOTFORM
- PRIMAL
- BLUESKY
- SNAPCHAT
- DESO
- PINTEREST
- FLICKR
- GALXE
- VELOG
- NPM
- PYPI
- HEX
- DOCKER_HUB
- VOCAL_MEDIA
- TECKFINE
- TENDERLY
- HACKMD
- ETSY
- ZAZZLE
- BASENAME
- BILIBILI_TV
- VIMEO
- DAILYMOTION
- PHONE_NUMBER
- SLACK
- CALENDLY
- NGROK
- RARIBLE
- RUST_PACKAGE
- FLATHUB
- VIDLII
- VEVIOZ
- ISSUU
- SOUNDCLOUD
- ZAPPER
- REDNOTE
- SAMSUNG_APP_STORE
- HUAWEI_APP_STORE
- XIAOMI_APP_STORE
- TENCENT_APP_STORE
- OPPO_APP_STORE
- VIVO_APP_STORE
- F_DROID
- GOOGLE_AD
- BING_AD
- TWITCH
- BEHANCE
- ZORA
- META_AD
- SIGNAL
- DEVIANTART
- BANDCAMP
- ARCHIVE_ORG
- FIVE_HUNDRED_PX
- LUMA
- SMARTMONEYMATCH
- in: query
name: brandIds
schema:
type: array
items:
type: number
- in: query
name: countryCodes
schema:
type: array
items:
type: string
minLength: 2
maxLength: 2
- in: query
name: sources
schema:
type: array
items:
type: string
enum:
- APP
- API
- CANARY_TOKEN
- AUTO_DETECTION
- ASSET_MANAGEMENT
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
reports:
type: array
items:
type: object
properties:
id:
type: number
title:
type: string
description:
type: string
imageDisplay:
type: string
enum:
- VISIBLE
- BLUR
- HIDDEN
favoritedAt:
type: string
nullable: true
status:
type: string
nullable: true
enum:
- TODO
- IN_PROGRESS
- CLOSED
- null
reportedByCustomer:
type: boolean
slaDueAt:
type: string
nullable: true
description: >-
SLA deadline for this report. `null` when no SLA
applies (e.g. staff-created reports). Compare with
the current time to identify reports that are late
or due soon.
externalSubmissionLink:
type: string
nullable: true
description: >-
URL to the original external source of the report,
when it was submitted from a third-party surface
(e.g. a Discord/Twitter message link, or a webform
we forwarded through). `null` for reports created
directly in ChainPatrol.
duplicateOfId:
type: number
nullable: true
description: >-
ID of the canonical report this one duplicates.
`null` when the report is not a duplicate. Group by
this to dedupe when counting unique reports.
createdAt:
type: string
updatedAt:
type: string
attachments:
type: array
items:
type: object
properties:
id:
type: number
url:
type: string
required:
- id
- url
proposals:
type: array
items:
type: object
properties:
reviewStatus:
type: string
enum:
- PENDING
- APPROVED
- REJECTED
asset:
type: object
properties:
id:
type: number
type:
type: string
enum:
- URL
- PAGE
- ADDRESS
- DISCORD
- LINKEDIN
- TWITTER
- FACEBOOK
- YOUTUBE
- REDDIT
- TELEGRAM
- GOOGLE_APP_STORE
- APPLE_APP_STORE
- AMAZON_APP_STORE
- MICROSOFT_APP_STORE
- TIKTOK
- INSTAGRAM
- THREADS
- MEDIUM
- CHROME_WEB_STORE
- MOZILLA_ADDONS
- OPERA_ADDONS
- EMAIL
- PATREON
- OPENSEA
- FARCASTER
- IPFS
- GOOGLE_FORM
- WHATSAPP
- DISCORD_USER
- QUORA
- GITHUB
- TEACHABLE
- SUBSTACK
- DEBANK
- TAWK_TO
- JOTFORM
- PRIMAL
- BLUESKY
- SNAPCHAT
- DESO
- PINTEREST
- FLICKR
- GALXE
- VELOG
- NPM
- PYPI
- HEX
- DOCKER_HUB
- VOCAL_MEDIA
- TECKFINE
- TENDERLY
- HACKMD
- ETSY
- ZAZZLE
- BASENAME
- BILIBILI_TV
- VIMEO
- DAILYMOTION
- PHONE_NUMBER
- SLACK
- CALENDLY
- NGROK
- RARIBLE
- RUST_PACKAGE
- FLATHUB
- VIDLII
- VEVIOZ
- ISSUU
- SOUNDCLOUD
- ZAPPER
- REDNOTE
- SAMSUNG_APP_STORE
- HUAWEI_APP_STORE
- XIAOMI_APP_STORE
- TENCENT_APP_STORE
- OPPO_APP_STORE
- VIVO_APP_STORE
- F_DROID
- GOOGLE_AD
- BING_AD
- TWITCH
- BEHANCE
- ZORA
- META_AD
- SIGNAL
- DEVIANTART
- BANDCAMP
- ARCHIVE_ORG
- FIVE_HUNDRED_PX
- LUMA
- SMARTMONEYMATCH
content:
type: string
status:
type: string
enum:
- UNKNOWN
- ALLOWED
- BLOCKED
scans:
type: array
items:
type: object
properties:
id:
type: number
status:
type: string
enum:
- PENDING
- IN_PROGRESS
- COMPLETED
- FAILED
output:
nullable: true
createdAt:
type: string
enrichments:
type: array
items:
type: object
properties:
id:
type: number
type:
type: string
output:
nullable: true
status:
type: string
required:
- id
- type
- status
required:
- id
- status
- createdAt
- enrichments
required:
- id
- type
- content
- status
- scans
required:
- reviewStatus
- asset
reporter:
type: object
nullable: true
properties:
id:
type: number
role:
type: string
enum:
- SUPERUSER
- SYSTEM
- CUSTOMER
- SUPPORT
- REVIEWER
- REPORTER
- MANAGER
- READ_ONLY
fullName:
type: string
avatarUrl:
type: string
nullable: true
required:
- id
- role
- fullName
- avatarUrl
externalReporter:
type: object
nullable: true
properties:
id:
type: number
displayName:
type: string
nullable: true
avatarUrl:
type: string
nullable: true
platform:
type: string
required:
- id
- displayName
- avatarUrl
- platform
source:
type: string
nullable: true
enum:
- APP
- API
- CANARY_TOKEN
- AUTO_DETECTION
- ASSET_MANAGEMENT
- null
sourceMetadata:
nullable: true
required:
- id
- title
- description
- imageDisplay
- favoritedAt
- status
- reportedByCustomer
- slaDueAt
- externalSubmissionLink
- duplicateOfId
- createdAt
- updatedAt
- attachments
- proposals
- reporter
- externalReporter
- source
nextCursor:
type: number
nullable: true
totalCount:
type: number
required:
- reports
- nextCursor
- totalCount
'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'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/error.NOT_FOUND'
'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.NOT_FOUND:
type: object
properties:
message:
type: string
description: The error message
example: Not found
code:
type: string
description: The error code
example: NOT_FOUND
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: Not found error (404)
description: The error information
example:
code: NOT_FOUND
message: Not found
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.
````