> ## Documentation Index
> Fetch the complete documentation index at: https://chainpatrol-mintlify-6c89fd48.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 full report records — proposals, assets, scans, reporter, and SLA metadata — with filtering and pagination, newest first. The organization is automatically inferred from your API key; if your credentials can reach more than one organization, pass an organization `slug` in the query to disambiguate.
Use this endpoint to browse or filter existing reports. To check whether a report already exists for a specific set of assets before filing a new one, use `POST /reports/search`, which looks reports up by asset content in a single batched call and returns a `totalCount` alongside the (capped) results.
## 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) |
## 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"
}
],
"slaDueAt": "2024-01-16T10:30:00.000Z",
"externalSubmissionLink": "https://discord.com/channels/123/456/789",
"duplicateOfId": null,
"imageDisplay": "PREVIEW",
"favoritedAt": null,
"attachments": []
}
],
"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. Each proposal exposes its nested `asset.scans[]` metadata for callers that need scan history alongside the proposal. |
| reports\[].slaDueAt | string \| null | ISO 8601 SLA deadline for the report. Use this to identify reports that are late without making a second healthcheck call. |
| reports\[].externalSubmissionLink | string \| null | Original external source URL (for example, a Discord message, X/Twitter post, or forwarded webform) when the report was submitted from a third-party surface. |
| reports\[].duplicateOfId | string \| null | ID of the canonical report when this report is a duplicate. Group reports by this field to dedupe counts. |
| reports\[].imageDisplay | string | How the report's images should be displayed in downstream UIs. |
| reports\[].favoritedAt | string \| null | ISO 8601 timestamp when the report was favorited by a reviewer. `null` when it isn't favorited. |
| reports\[].attachments | array | Attachments uploaded with the report (screenshots, evidence files, etc.). |
| cursor | string | Cursor for the next page of results (undefined if no more results) |
All new fields are additive — existing integrations continue to work unchanged.
## 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'
```
## 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.
````