Skip to main content
A credential comparison report compares the leaked credentials found across a set of domains over a period you choose. Put an organization’s brands, subsidiaries or country domains side by side, and hand the result to people who do not use the API. The download is a ZIP file. It holds the report as a Word document and CSV files with the findings behind it. Every report runs asynchronously. You start it, poll it until it is ready, then download the file.
Reports have their own flow. For search-result exports, monitor match downloads and original leak files, see Downloads and exports. Attack Surface assessments have their own reports: see Attack Surface reports.

​
Availability and cost

Availability: Credential Report, included in every plan. Monthly schedules are also in every plan and need only a license in force. An active schedule holds a Scheduled reports slot. Cost: 1 unit of your monthly Credential Report allowance for each report you generate on demand. The unit is taken before the report is created and refunded if generate_credential_comparison_report returns anything other than 2xx. A report that ends in Error keeps its unit, and so does a report you delete. Reports that a schedule produces use the schedule’s slot, not Credential Report units. Status, list, download and delete calls use no units. Without the feature, or when your license is not active, generate_credential_comparison_report returns 403:
get_report_status, list_report_requests, download_report and delete_report have no plan or license check, so the reports you already generated stay readable. The schedule endpoints, including list_scheduled_reports, need a license in force. When the month’s allowance is spent, generate_credential_comparison_report returns 429 and no report is created:
limit is your monthly allowance, packs included. The allowance resets at 00:00 UTC on the 1st of the month. Do not retry before then. A 429 whose body reads "message": "Rate limit exceeded" comes from the per-second rate limit or the API Calls allowance instead. See Rate limits. Report schedules have their own refusals, including 409 when no slot is free.

​
On demand or every month

A schedule runs on the 1st of each month and covers the previous calendar month. You track, download and delete its reports the same way as on-demand ones.

Credential comparison report

Request fields, validation rules, and how to create, pause and edit a monthly schedule.

​
Generate, track and download

1

Start the report

Send the domains to compare and the period, in dd-mm-yyyy:
The call returns 201:
Keep the report_id. The status, download and delete calls all take it.
2

Poll until it ends

Call get_report_status with the report_id.
  • id — the report ID.
  • type — the report type, credential_comparison.
  • status — the generation state, as readable text.
  • metadata — what the report covers: domain, period_type, started_at, ended_at and mask_passwords. domain takes the same form as on the list rows.
get_report_status returns readable text. The list calls return the same states as short codes. Compare against the value of the call you use.Poll every 30 to 60 seconds and stop at Report ready or Error. Each poll that returns 200 uses one API call.
3

Download the ZIP file

Once the status is Report ready, fetch the file with download_report.
The response streams the file with the content type and file name the report service sets. --fail stops curl from saving a JSON error body as the file.Called before the report is ready, download_report returns 400 with a message. Keep polling, then retry.

​
List reports

list_report_requests returns your organization’s reports, on-demand and scheduled, one page at a time.
All parameters are optional:
  • page — 1-based. Defaults to 1.
  • page_size — defaults to 10, max 100.
  • report_type — credential_comparison returns only credential comparison reports.
  • status — started, in_progress, ready or error.
  • domain — filters on the report’s domain field.
  • ordering — create_date, -create_date, update_date or -update_date.
Raise page until it reaches total_pages. Each row carries:
  • id — the report_id for the status, download and delete calls.
  • type and status — the report type and its generation state.
  • domain — the domains the report covers. On a credential comparison report it can hold them as a JSON-encoded list, as in the example. Parse it when it starts with [.
  • from_date / to_date — the report period, in dd-mm-yyyy.
  • frequency — on_demand for a one-off report, monthly for a report a schedule produced.
  • mask_passwords — whether leaked passwords are masked in the report.
  • created_at / updated_at — when the report was created and last updated, in dd-mm-yyyy HH:MM:SS.
To list only the reports one schedule produced, call list_scheduled_reports. See Credential comparison report.

​
Delete a report

delete_report removes a report and returns 204. Deleting does not refund the report’s Credential Report unit.
A report that is still processing cannot be deleted, and the call returns 409. Delete it once its status is ready or error.

​
Errors

Any other 429 on generate_credential_comparison_report comes from the report service, and its unit is refunded. After a 502 or 504 on generate_credential_comparison_report, list your reports before you send it again: the report may have started. Errors explains how to handle each status.

​
Endpoints