Search API


The Search API exposes a single endpoint, /api/v1/search, which is used for all searches. Once resulting records have been found, full records can be fetched using the View API Endpoint.

Search


Description

The search endpoint allows searches against the current data in the IPv4, Top Million Websites, and Certificates indexes using the same search syntax as the primary site. The endpoint returns a paginated result set of hosts (or websites or certificates) that match the search. Data should be posted as a JSON request document.

Endpoint
POST /api/v1/search/:index
URL Parameters
  • index [required string]
    The search index to be queried. Must be one of ipv4, websites, or certificates.
Example: /api/v1/search/certificates
Data Parameters
  • query [required string]
    The query to be executed. For example, 80.http.get.headers.server: nginx.
  • page [optional integer]
    The page of the result set to be returned. The number of pages in the result set is available under metadata in any request. By default, the API will return the first page of results. One indexed.
  • fields [optional list of strings]
    The fields you would like returned in the result set in "dot notation", e.g. location.country_code.
  • flatten [optional boolean]
    Format of the returned results. Default is flattened (flatten=true).

    Nested Example:
    {
        "ip": "173.205.31.126",
        "location": {
            "city": "Ann Arbor",
            "country": "United States"
        }
    }
    Flattened Example:
    {
        "ip": "173.205.31.126",
        "location.city": "Ann Arbor",
        "location.country": "United States",
    }
Example:
{
  "query":"80.http.get.headers.server: Apache",
  "page":1,
  "fields":["ip", "location.country", "autonomous_system.asn"],
  "flatten":true
}
Success Response
200 SUCCESS
The search or query executed successfully.
Example:
{
  "status": "ok",
  "metadata": {
    "count": 127530942,
    "query": "*",
    "backend_time": 263,
    "page": 1,
    "pages": 1275310
  },
  "results": [
    {
      "ip": "173.205.31.126",
      "protocols": [
        "80\/http",
        "443\/https"
      ]
    },
    {
      "ip": "213.149.206.213",
      "protocols": [
        "80\/http"
      ]
    },

    ...

    {
      "ip": "84.206.102.184",
      "protocols": [
        "80\/http"
      ]
    }
  ]
}
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"}
  • 404 NOT FOUND
    Specified search index was not valid.
    Example:
    {"error_code":404, "error":"page not found"}
  • 429 RATE LIMIT EXCEEDED
    Your query was not executed 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"}