Natural Language Search

Ask for compromised credentials in plain English. GET /breaches/ask interprets your question - the domain, sources, time window, and order - and runs the standard Data Breaches search, returning the same structured records as /breaches.

Use it for investigations, analyst tooling, and chat assistants, or to find the right /breaches filters quickly. For automated pipelines that need fixed, repeatable parameters, call /breaches directly.

Request

GET

https://api.webz.io/breaches/ask?q=YOUR_QUESTION

Authentication

Send your Webz.io API token as a Bearer header:

Authorization: Bearer YOUR_TOKEN

The token query parameter also works, as on every other Data Breaches endpoint. The header is recommended: URLs are often recorded in proxy logs and command history. Your account needs the Data Breaches permission and authorization for the domain you ask about - see Errors, Rate Limits & Credits.

Preview with dry_run

Check how a question is understood before running it:

curl --get 'https://api.webz.io/breaches/ask' \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode 'q=Which example.com employees had credentials exposed in the last 30 days, newest first?' \
  --data-urlencode 'dry_run=true'

{
  "interpretedQuery": "/breaches?email_domain=example.com&order_by=desc&sort_by=crawled&crawled_from=1790294400000",
  "params": {
    "email_domain": "example.com",
    "order_by": "desc",
    "sort_by": "crawled",
    "crawled_from": 1790294400000
  }
}

interpretedQuery is the equivalent /breaches call, without your token. If it is not what you meant, rephrase and preview again. A preview never runs the search and costs no credit.

Run a search

Omit dry_run to run the interpreted search:

curl --get --include 'https://api.webz.io/breaches/ask' \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode 'q=Show the latest leaked logins to example.com from infostealers in the last 60 days'

The X-Interpreted-Query header shows the /breaches query that produced the results, token excluded:

HTTP/1.1 200 OK
X-Interpreted-Query: /breaches?login_domain=example.com&data_type=infostealer&order_by=desc&sort_by=crawled&crawled_from=1787702400000

The body is the standard Response Format, up to 100 records per page:

{
  "records": [ ... ],
  "totalResults": 412,
  "moreResultsAvailable": 312,
  "next": "/breaches?login_domain=example.com&data_type=infostealer&order_by=desc&sort_by=crawled&crawled_from=1787702400000&token=YOUR_TOKEN&next=CURSOR",
  "requestsLeft": 988,
  "totalResultsVerified": true
}

What you can specify

Every question names one domain or one email address. Beyond that, include any of the following:

• Who - employee accounts (email addresses at the domain) or customer accounts (credentials used to sign in to the domain, subdomains included).
• Sources - data breaches, infostealer logs, or both. Both are searched unless the question restricts them.
• Credential details - records that contain a password, or a specific password type.
• Service - a service category or application, such as VPN access.
• Time window - by collection date or by breach/infection date, within the last 365 days. Without a period, the search covers the last 365 days.
• Order - newest or oldest first (oldest first by default).
• A specific breach - by name, matched against the Breach Catalog.

Example questions:

• Which example.com employees had credentials exposed in the last 30 days, newest first?
• Show the latest infostealer records with logins to example.com from the last 60 days.
• Show example.com accounts with plaintext passwords from data breaches collected this year.
• Show VPN logins to example.com from devices infected in the last six months, by infection date.

Pagination

next in the response is a ready-made /breaches URL. Append it to https://api.webz.io and call it as-is, exactly as in Pagination for a direct search. Do not send next back through /breaches/ask: the question is interpreted once, and paging continues through /breaches.

Credits and rate limits

requestsLeft in every search response shows your balance. The per-token rate limit of about 1 request per second applies to the search, as on /breaches.

Interpreting a question takes longer than a direct /breaches call. For high-volume or latency-sensitive workloads, resolve the question once with dry_run and reuse the resulting /breaches query.

When the question cannot be run

If the question is missing something, or asks for what the API cannot do, the endpoint returns 400 with a plain-language explanation instead of guessing. The wording varies; for example:

{
  "errorCode": 400,
  "errors": [
    "Which domain or email address should be searched?"
  ]
}

Common reasons:

• No domain or email address in the question, or more than one domain - search one at a time.
• A time range older than 365 days - natural language search covers the last year only. For older data, use /breaches with raw=true; see Time Range.
• A named breach that is unknown or matches several catalog entries - the message lists the candidates. Specify one and retry.

Rephrase and retry; a clarification costs no credit. Other errors follow the Data Breaches conventions - 400 for a blank q or one over 500 characters, 401 for a missing token or no Data Breaches permission, 403 for an unauthorized domain, 404 for an unknown token, 429 for the rate limit or no credits. See Errors, Rate Limits & Credits.

Limits

• One domain or one full email address per question.
• q is at most 500 characters.
• Searches cover the last 365 days. Raw mode is not available here.
• q is the whole search: other /breaches parameters on the request are ignored.
• No next or page-size parameter - page through /breaches.
• Up to 100 records per page.

Privacy

• Your question is sent to an external language-model service to be interpreted. Your API token and the returned records are not - the service only sees the text of q.
• q travels in the URL and may appear in access logs. Keep passwords, tokens, and personal data out of it unless they are what you are searching for, such as an email address.
• Results come straight from the Data Breaches index. Nothing in a record is generated or altered by AI.

Related documentation

• Quickstart
• Search Scope
• Filters
• Response Format
• Pagination
• Errors, Rate Limits & Credits