Report API


The Report API exposes a single endpoint, /api/v1/report, which can be used to create aggregate reports on the breakdown of a field in the result set of a query.

Create Report


Description

The build report endpoint lets you run aggregate reports on the breakdown of a field in a result set analogous to the "Build Report" functionality in the front end. For example, if you wanted to determine the breakdown of cipher suites selected by Top Million Websites. Data should be posted as a JSON request document.

Endpoint
POST /api/v1/report/:index
URL Parameters
  • index [required string]
    The search index the document is in. Must be one of ipv4, websites, or certificates.
Example: /api/v1/report/ipv4
Data Parameters
  • query: [required string]
    The query to be executed. For example, 80.http.get.headers.server: nginx.
  • field: [required string]
    The field you are running a breakdown on in "dot notation", e.g. location.country_code.
  • buckets: [optional int]
    The maximum number of values to be returned in the report. Maximum: 500. Default: 50.

Example:

{
  "query":"80.http.get.headers.server: Apache",
  "field":"location.country",
  "buckets":100
}
Success Response
200 SUCCESS
The record was successfully retreived.
Example:
{
  "status": "ok",
  "results": [
    {
      "key": "80\/http",
      "doc_count": 60360211
    },
    {
      "key": "443\/https",
      "doc_count": 55055587
    },
    {
      "key": "7547\/cwmp",
      "doc_count": 38971729
    },
    {
      "key": "21\/ftp",
      "doc_count": 13434960
    },
    {
      "key": "25\/smtp",
      "doc_count": 8967614
    }
  ],
  "metadata": {
    "count": 130517957,
    "backend_time": 1599,
    "nonnull_count": 206619766,
    "other_result_count": 29829665,
    "buckets": 5,
    "error_bound": 0,
    "query": "*"
  }


}
Error Responses
  • 400 BAD REQUEST
    Your query could not be executed (e.g., query could not be parsed or timed out.) See error for more information.
    Example:
    {"error_code":400, "error":"query could not be parsed"}
  • 429 RATE LIMIT EXCEEDED
    The requested record was not retrieved because you have exceeded your specified rate limit.
    Example:
    {"error_code":429, "error":"rate limit exceeded"}
  • 500 INTERNAL SERVER ERROR
    An unexpected error occurred when trying to execute your query. Try again at a later time or contact us at requests@censys.io if the problem persists.
    Example:
    {"error_code":500, "error":"unknown error occurred"}