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.

GET /organization/reports

List organization reports

cURL

curl --request GET \
  --url https://app.chainpatrol.io/api/v2/organization/reports \
  --header 'X-API-KEY: <api-key>'

200

{
  "reports": [
    {
      "id": 123,
      "title": "<string>",
      "description": "<string>",
      "favoritedAt": "<string>",
      "reportedByCustomer": true,
      "slaDueAt": "<string>",
      "externalSubmissionLink": "<string>",
      "duplicateOfId": 123,
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "attachments": [
        {
          "id": 123,
          "url": "<string>"
        }
      ],
      "proposals": [
        {
          "asset": {
            "id": 123,
            "content": "<string>",
            "scans": [
              {
                "id": 123,
                "createdAt": "<string>",
                "enrichments": [
                  {
                    "id": 123,
                    "type": "<string>",
                    "status": "<string>",
                    "output": null
                  }
                ],
                "output": null
              }
            ]
          }
        }
      ],
      "reporter": {
        "id": 123,
        "fullName": "<string>",
        "avatarUrl": "<string>"
      },
      "externalReporter": {
        "id": 123,
        "displayName": "<string>",
        "avatarUrl": "<string>",
        "platform": "<string>"
      },
      "sourceMetadata": null
    }
  ],
  "nextCursor": 123,
  "totalCount": 123
}

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:

X-API-KEY: your_api_key_here

Example Request

TypeScript

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);

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

{
  "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

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));

Filtering Examples

Filter by Date Range

Get reports from a specific time period:

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:

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:

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:

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:

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.

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:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key with organization access required"
  }
}

400 Bad Request

Returned when query parameters are invalid:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid date format. Use ISO 8601 format."
  }
}

Use Cases

Monitor Recent Reports

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

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

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

Authorizations

X-API-KEY · string · header · required

Your API key. This is required by most endpoints to access our API programatically. Reach out to us at [e-mail] to get an API key for your use.

Query Parameters

limit · number · required

Required range: 1 <= x <= 20

cursor · number | null

status · enum<string>

Available options: TODO, IN_PROGRESS, CLOSED

searchQuery · string

reporterQuery · string

reporterKind · enum<string>

Available options: human, automation

reviewerKind · enum<string>

Available options: human, automation

reviewedByUserId · number | null

startDate · string

endDate · string

updatedAtStartDate · string

updatedAtEndDate · string

registrars · string[]

hasMxRecords · boolean

slug · string

excludeAutomation · boolean · default: false

onlyRejected · boolean · default: false

onlyFavorited · boolean · default: false

reportedByCustomer · boolean

needsCustomerReview · boolean

reviewStatuses · enum<string>[]

Available options: APPROVE, REJECT, SKIP, ESCALATE

assetTypes · enum<string>[]

Available options: 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

brandIds · number[]

countryCodes · string[]

Required string length: 2

sources · enum<string>[]

Available options: APP, API, CANARY_TOKEN, AUTO_DETECTION, ASSET_MANAGEMENT

Response

200

application/json

Successful response

reports · object[] · required

Show child attributes

nextCursor · number | null · required

totalCount · number · required