BBB Scam Reports Search API

Endpoint facts

Method

GET

API path

/datasets/bbb-scamtracker-reports/search

Auth

apiKey

Credits

1 credit/record returned · minimum 2

Charged on

Successful 2xx responses only

Platform

Datasets

Execution

Stored dataset records. No live scraping, browser session or proxy routing.

Response schema

#/definitions/datasets.scamTrackerReportsSearchResponseDoc

How this endpoint behaves

Query parameters:

• q: optional full-text match on the report narrative and the business name used, max 256 characters.
• scam_type: optional exact scam type filter, e.g. Online Purchase. Use the values returned by facets?facet=scam_type.
• state: optional 2-letter state or province code of the targeted person, e.g. TX or QC.
• country: optional country of the targeted person. Allowed values: USA, CAN.
• date_from: optional inclusive report-date floor, YYYY-MM-DD.
• date_to: optional inclusive report-date ceiling, YYYY-MM-DD. Must not be before date_from.
• min_loss: optional floor against the reported dollar loss, 0 or greater.
• max_loss: optional ceiling against the reported dollar loss, 0 or greater. Must not be below min_loss.
• sort: optional sort order. Allowed values: relevance, reported_desc, reported_asc, loss_desc. Defaults to relevance with q, otherwise reported_desc.
• page: optional page number, defaults to 1.
• page_size: optional page size, defaults to 20 and maxes at 100.

Response behavior:

• Each item carries report_id, description (the narrative), scam_type, dollars_lost (as BBB shows it, e.g. $149 or Unknown), loss_amount (the same loss as a number, left out when BBB shows no amount), targeted_location, state and country (derived from the targeted location when it names a US state or Canadian province), scammer_location, scammer_email, scammer_phone, scammer_url, business_name (the business name the report says was used), date_reported (as BBB shows it), reported_at (the same date as an ISO timestamp), source_url, discovery_source, crawled_at and schema_version.
• total is the number of stored reports matching the filters, not BBB's own count. The archive is filled continuously by a date census of BBB's search and by Common Crawl, and is not complete; a report missing here can still be read live with bbb-scamtracker-detail.
• min_loss and max_loss exclude reports with an unknown loss. An unknown loss is never stored as 0.
• A report whose targeted location names no US state or Canadian province has no state or country and is not matched by those filters.
• The maximum result window is 10000; page * page_size must not exceed 10000. To read more than that, split the range with date_from/date_to (a month, then a week or a day if needed).
• Invalid enum values, dates and ranges return the standard invalid params envelope.
• Returns an empty items array (not an error) when nothing matches.
• Does not trigger live scraping.
• Billing: 1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. Use facets (1 credit) to size a query before paging through it.

Example response (the report is the one in the bbb-scamtracker-detail docs; discovery_source and crawled_at are illustrative):

{
  "code": 200,
  "msg": "OK",
  "data": {
    "dataset": "bbb-scamtracker-reports",
    "items": [
      {
        "report_id": "1397968",
        "description": "AltRX has taken $149 and is stringing me along about my 2nd delivery. They deducted money from my account with no product being delivered",
        "dollars_lost": "$149",
        "loss_amount": 149,
        "targeted_location": "Chesapeake, VA, USA - 23322",
        "country": "USA",
        "state": "VA",
        "scammer_location": "GA",
        "scammer_email": "Unknown Email",
        "scammer_phone": "Unknown Phone Number",
        "scammer_url": "Unknown URL",
        "scam_type": "Online Purchase",
        "business_name": "AltRX",
        "date_reported": "August 19, 2026",
        "reported_at": "2026-08-19T00:00:00Z",
        "source_url": "https://www.bbb.org/scamtracker/lookupscam/1397968",
        "discovery_source": "search",
        "crawled_at": "2026-10-09T04:12:31Z",
        "schema_version": 1
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 1,
    "sort": "reported_desc"
  }
}

Sampled response

Request, 14 Oct 2026

GET /datasets/bbb-scamtracker-reports/search?page_size=20

Items in items

20

Fields filled in every checked item

17

Fields empty in some or all items

2

Shared guides

Related