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>",
      "imageDisplay": "VISIBLE",
      "favoritedAt": "<string>",
      "status": "TODO",
      "reportedByCustomer": true,
      "slaDueAt": "<string>",
      "externalSubmissionLink": "<string>",
      "duplicateOfId": 123,
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "attachments": [
        {
          "id": 123,
          "url": "<string>"
        }
      ],
      "proposals": [
        {
          "reviewStatus": "PENDING",
          "asset": {
            "id": 123,
            "type": "URL",
            "content": "<string>",
            "status": "UNKNOWN",
            "scans": [
              {
                "id": 123,
                "status": "PENDING",
                "createdAt": "<string>",
                "enrichments": [
                  {
                    "id": 123,
                    "type": "<string>",
                    "status": "<string>",
                    "output": null
                  }
                ],
                "output": null
              }
            ]
          }
        }
      ],
      "reporter": {
        "id": 123,
        "role": "SUPERUSER",
        "fullName": "<string>",
        "avatarUrl": "<string>"
      },
      "externalReporter": {
        "id": 123,
        "displayName": "<string>",
        "avatarUrl": "<string>",
        "platform": "<string>"
      },
      "source": "APP",
      "sourceMetadata": null
    }
  ],
  "nextCursor": 123,
  "totalCount": 123
}

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:

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)

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"
        }
      ],
      "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

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'

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