Hosts Search API

The Hosts Search API exposes a single endpoint, /api/v2/hosts/search, which can be used to search for hosts using the Censys Search Language.

Cursor Pagination

Search endpoints rely on using cursors for efficient pagination

Each search result may return a next and prev cursor value which can be used to fetch additional pages of results.

{
   "links":{
      "prev":"prevCursorToken",
      "next":"nextCursorToken"
   },
   [Rest of Response]
}
      
The returned cursor token value can be included with a subsequent call to a search endpoint to fetch either the next page of results when given the next cursor or the previous page when given the prev cursor.

The entire set of results can be iterated page-by-page using returned cursors. If no cursor is given, the first page will be returned.

Details

Description

List hosts that match the given query string. See help on the Censys Search Language for help on constructing a search query.

Endpoint
GET /api/v2/hosts/search
Path Parameters
(none)
Query Parameters
  • q [optional string]
    Query used to search for Hosts. Query uses the Censys Search Language.
  • per_page [optional int]
    The maximum number of Hits to show per API response. Minimum of 0. Maximum of 100. If not specified, 50 results will be returned by default.
  • cursor [optional string]
    Cursor token, when supplied, will fetch either the next or previous page of results matching the rest of the given query parameters.
Example: /api/v2/hosts/search?q=services.service_name%3AHTTP&per_page=100
Searches for Hosts which have an HTTP service, showing up to 100 hits at a time.
Body Parameters
(none)
Success Response
200 SUCCESS
The search executed successfully.
Example:
{
  "query":"service.service_name: HTTP",
  "hits":[
     {
        "services":[
           {
              "service_name":"HTTP",
              "port":80
           }
        ],
        "ip":"1.0.0.0"
     }
  ],
  "total":125746846,
  "links":{
     "prev":"",
     "next":"eyJBZnRlciI6WyIxIiwiMS4wLjAuMCJdLCJSZXZlcnNlIjpmYWxzZX0="
  }
}