Search 2.0 API Quick Start
The quickest way to get started with the Censys Search 2.0 API is to visit our API docs, where you can try out all of the API calls right from the page.

This tutorial introduces key concepts and walks you through select examples of the API’s core functionality.
Connecting to the API
Search API endpoints are hosted at https://search.censys.io/api/
Authentication
Every call to the API requires authentication with HTTP basic auth using the API ID and secret shown on the My Account page.

This page also lists the rate limits that apply to your account.
v2 Responses
Every v2 endpoint response includes:
-
Status
-
Result
Example Response
The example below shows a response from the host aggregate endpoint. The response contains the HTTP status and the result. In the result, two fields echo the request, and the actual breakdown of TLS version usage.
{ "code": 200, // Status "status": "OK", // Status "result": { "query": "services.tls: *", // Used to select hosts for evaluation "field": "services.tls.version_selected", // The host field whose values are become the buckets "total": 239226493, // Total number of hosts whose TLS values were tallied "buckets": [ { "key": "TLSv1_2", "count": 108934487 }, { "key": "TLSv1_1", "count": 690044 }, { "key": "TLSv1_0", "count": 4855982 }, { "key": "SSLv3", "count": 92406 } ], "total_omitted": 0, // The number of hosts omitted from the aggregation "potential_deviation": 0 } }
Host Endpoints
Hosts are identified by an IP address. Virtual hosts are identified by an IP address and name, joined by a plus sign (+).
You can use the API to search for hosts, compare hosts, view a single host in its current state or at a historical point in time, retrieve a chronology of host events, obtain a list of current names the host responded to in scan, and more.
The endpoints introduced below highlight the use and usefulness of the API, but are not exhaustive by any means.
A sampling of endpoints that take the HTTP GET
method:
-
Search (
/v2/hosts/search
) — Search for hosts using the Censys Search Language. -
Aggregate (
/v2/hosts/aggregate
) — Generate a report about the frequency of values seen for a specified field across all hosts matching a search. -
View (
v2/hosts/{id}
) — View a host as it is known to Censys currently or at a historical point in time. -
Diff (
v2/hosts/{ip}/diff
) — List the transformations that would turn one host into another. -
Events (
/v2/hosts/{id}/events
) — List events documenting observed changes in the host’s data over time. -
Names (
/v2/hosts/{id}/names
) — List the names that the host responded to during a scan.
Search Hosts
Search hosts by submitting a query written in the Censys Search Language. This endpoint returns a paginated result with a preview of the hosts whose attributes match the submitted query.
Full details about the matching hosts must be fetched individually using the View endpoint.
Method and Path
GET /v2/hosts/search
URL Parameters
None
Query Parameters
Query parameters should be added to the path after a leading question mark (?
), separated by an ampersand (&
).
Parameter | Required? | Type | Description | Example |
---|---|---|---|---|
q |
optional |
string |
The query to be executed, written in the Censys Search Language |
|
per_page |
optional |
integer |
The number of results to be returned (max: 100, default: 50) |
|
cursor |
optional |
string |
The base-64-encoded string of the next or prev page cursor returned in the API response |
|
Example Search Request
Search for (the next page of) hosts with an HTTP service reporting "nginx" in the server header.
GET \https://search.censys.io/api/v2/hosts/search?q=services.http.response.headers.server%3A%20nginx&per_page=1&cursor=eyJBZnRlciI6WyIxLjAuMTAzLjkiLCJcdTAwM2NuaWxcdTAwM2UiXSwiUmV2ZXJzZSI6ZmFsc2UsIlNlZWQiOjB9=
Example Success Response
The search executed successfully and found 19,788,926 hosts matching the query.
One result is printed out, as specified by the per_page
parameter.
{ "code": 200, "status": "OK", "result": { "query": "services.http.response.headers.server: nginx", "total": 19788926, "duration": 103, "hits": [ { "ip": "1.0.112.130", "services": [ { "port": 5006, "service_name": "HTTP", "certificate": "760daa3d7a9bdd8d18b552300537cf8fadf72ba59196154bf902c3e3ab5d1e94", "transport_protocol": "TCP" }, { "port": 49924, "service_name": "HTTP", "certificate": "760daa3d7a9bdd8d18b552300537cf8fadf72ba59196154bf902c3e3ab5d1e94", "transport_protocol": "TCP" }, { "port": 58355, "service_name": "HTTP", "transport_protocol": "TCP" }, { "port": 58357, "service_name": "HTTP", "transport_protocol": "TCP" } ], "location": { "continent": "Asia", "country": "Japan", "country_code": "JP", "city": "Shimonoseki", "postal_code": "750-0011", "timezone": "Asia/Tokyo", "province": "Yamaguchi", "coordinates": { "latitude": 33.9564, "longitude": 130.939 }, "registered_country": "Japan", "registered_country_code": "JP" }, "autonomous_system": { "asn": 18144, "description": "AS-ENECOM Energia Communications,Inc.", "bgp_prefix": "1.0.64.0/18", "name": "AS-ENECOM Energia Communications,Inc.", "country_code": "JP" }, "last_updated_at": "2022-11-07T12:37:29.030Z", "dns": { "reverse_dns": { "names": [ "130.112.0.1.megaegg.ne.jp" ] } }, "matched_services": [ { "port": 58355, "service_name": "HTTP", "transport_protocol": "TCP" }, { "port": 58357, "service_name": "HTTP", "transport_protocol": "TCP" } ] } ], "links": { "next": "eyJBZnRlciI6WyIxLjAuMTEyLjEzMCIsIlx1MDAzY25pbFx1MDAzZSJdLCJSZXZlcnNlIjpmYWxzZSwiU2VlZCI6MH0=", "prev": "eyJBZnRlciI6WyIxLjAuMTEyLjEzMCIsIlx1MDAzY25pbFx1MDAzZSJdLCJSZXZlcnNlIjp0cnVlLCJTZWVkIjowfQ==" } } }
View a Host
View a host as it is known to Censys now or at a historical point in time. Nanosecond precision (9 decimal places) is supported.
This endpoint is frequently used in conjunction with the Search endpoint, which returns a list of hosts that match a query.
Method and Path
GET /v2/hosts/{ip}
URL Parameters
Parameter | Required? | Type | Description | Example |
---|---|---|---|---|
id |
required |
string |
The IP address of the host or the IP address/name of the virtual host |
|
Query Parameters
Query parameters should be added to the path after a leading question mark ?
, separated by an ampersand (&
).
Parameter | Required? | Type | Description | Example |
---|---|---|---|---|
at_time |
optional |
string |
A historical timestamp formatted according to RFC-3339 |
|
Example View Request
View host 160.13.89.64 as it was known to Censys on October 10, 2022 at 11:19:00.000 PM UTC.
`GET https://search.censys.io/api/v2/hosts/160.13.89.64?at_time=2022-10-19T11%3A19%3A00.000Z `
Example Success Response
The host record was successfully retrieved, showing a single unknown service running on port 7070 using TLS 1.2 encryption and presenting a self-signed certificate.
{ "code": 200, "status": "OK", "result": { "ip": "160.13.89.64", "services": [ { "service_name": "UNKNOWN", "extended_service_name": "UNKNOWN", "port": 7070, "observed_at": "2022-10-09T16:36:02.609189134Z", "perspective_id": "PERSPECTIVE_NTT", "source_ip": "167.248.133.44", "_decoded": "banner_grab", "_encoding": { "banner": "DISPLAY_UTF8", "certificate": "DISPLAY_HEX" }, "banner": "", "banner_grab": { "transport": "TCP" }, "banner_hashes": [ "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ], "certificate": "7264f98ffc0f3f1e3cf1d8cc96c666b78ff1167224db00cb07445d914e3accca", "tls": { "version_selected": "TLSv1_2", "cipher_selected": "TLS_RSA_WITH_AES_128_GCM_SHA256", "certificates": { "_encoding": { "leaf_fp_sha_256": "DISPLAY_HEX" }, "leaf_fp_sha_256": "7264f98ffc0f3f1e3cf1d8cc96c666b78ff1167224db00cb07445d914e3accca", "leaf_data": { "subject_dn": "CN=AnyDesk Client", "issuer_dn": "CN=AnyDesk Client", "pubkey_bit_size": 2048, "pubkey_algorithm": "RSA", "tbs_fingerprint": "ce2452106b7c354414f2cb146aa503614c21858e22589c47f52945532da8269d", "fingerprint": "7264f98ffc0f3f1e3cf1d8cc96c666b78ff1167224db00cb07445d914e3accca", "issuer": { "common_name": [ "AnyDesk Client" ] }, "subject": { "common_name": [ "AnyDesk Client" ] }, "public_key": { "key_algorithm": "RSA", "rsa": { "_encoding": { "modulus": "DISPLAY_BASE64", "exponent": "DISPLAY_BASE64" }, "modulus": "upGsJCnXOgesLlW0jDuolFwFDc0VCQp5xwX0PlXrT8PtZPOdHOQpAo+kBZRCHPY9eFGRHQeplj/0cEEb9YSzXjlrV2fztbBkz1v6J18PW69MgFMLiwAJzlcYIGPvZoztMtckftHeYt3LTJK9Um7ITWn0BLUCH0VYOdKRCstnUhzrjHvIbct5uaSfIxoFObGakrlbXTgP5G/+r9HP/Cd1+boiq7a+73UjI51uRIFF2RAPOsayG2cpcK5M3XJhpY/vBUABVXx+qzaqy0dgyxDC0vmJAYcLiUtL/BbFnbVMkoyyp92UoWxoT6EjkAO+NAyLVbpx7NnmwjRV9tBG6O+kjQ==", "exponent": "AAEAAQ==", "length": 256 }, "fingerprint": "9f45934d82bbc75787675d939a802e40631637f8d04c855ac0150a3d9026f379" }, "signature": { "self_signed": true, "signature_algorithm": "SHA256-RSA" } } }, "_encoding": { "ja3s": "DISPLAY_HEX" }, "ja3s": "ccd5709d4a9027ec272e98b9924c36f7" }, "transport_fingerprint": { "raw": "65535,128,true,MNWNNS,1414,false,false" }, "transport_protocol": "TCP", "truncated": false } ], "location": { "continent": "Asia", "country": "Japan", "country_code": "JP", "city": "Shibuya", "postal_code": "150-6011", "timezone": "Asia/Tokyo", "province": "Tokyo", "coordinates": { "latitude": 35.6654, "longitude": 139.6977 }, "registered_country": "Japan", "registered_country_code": "JP" }, "location_updated_at": "2022-10-09T16:36:05.839715Z", "autonomous_system": { "asn": 2497, "description": "IIJ Internet Initiative Japan Inc.", "bgp_prefix": "160.13.0.0/16", "name": "IIJ Internet Initiative Japan Inc.", "country_code": "JP" }, "autonomous_system_updated_at": "2022-10-09T16:36:05.839494Z", "dns": {}, "last_updated_at": "2022-10-09T16:36:05.857Z" } }
Certificates
Certificates are identified by a SHA-256 digest of their content (referred to as a fingerprint
or fp
).
Search for and view certificates using v1
endpoints.
Tag, comment on, and obtain a list of hosts presenting a certificate on v2
endpoints.
The endpoints introduced below highlight the use and usefulness of the API, but are not exhaustive by any means.
These endpoints use a mixture of methods (POST
, GET
) and paths (v1/v2
):
-
"Hosts by Cert" (
v2/certificates/{fp}/hosts
) — Lists the hosts that are currently presenting a certificate. -
Search (
v1/search/certificates
) — Search for hosts using the Censys Search Language. -
Report (
v1/report/certificates
) — Generate a report about the values for a specified field across all certs matching a search. -
View (
v1/view/certificates/{fp}
) — View a host as it is known to Censys currently or at a historical point in time.
List Hosts Presenting a Certificate
See a list of hosts that are currently presenting a certificate during a TLS handshake.
Method and Path
GET /v2/certificates/{fp}/hosts
URL Parameters
Parameter | Required? | Type | Description | Example |
---|---|---|---|---|
fp |
required |
string |
The SHA-256 fingerprint of the cert |
|
Query Parameters
None.
Example View Hosts by Cert Request
Return of a lists of hosts presenting certificate 6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01.
GET /v2/certificates/6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01/hosts
Example Response
The one host, identified by its IP address, that is presenting the certificate and the time that it was presented.
{ "code": 200, "status": "OK", "result": { "fingerprint": "6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01", "hosts": [ { "observed_at": "2021-11-02T09:43:48.446082119Z", "ip": "52.14.77.60" } ], "links": { "next": "" } } }
Search Certificates
Search certificates by submitting a query written in the legacy query syntax. This endpoint returns a paginated result with the certificate fields specified in the search request.
Method and URL
POST v1/search/certificates
URL Parameters
None
Query Parameters
None
Data Parameters
Data parameters should be posted as a JSON request document.
Parameter | Required? | Type | Description | Example |
---|---|---|---|---|
query |
required |
string |
The query to be executed |
|
page |
optional |
integer |
The page of the result set to be returned |
|
fields |
optional |
array[string] |
The fields you would like returned in the result with keys written out in "dot notation" |
|
flatten |
optional |
boolean |
Format of the returned results. Default is flattened. |
|
Example Search Request
Return SHA-256 fingerprints of self-signed certificates whose names section contains "censys.io" that have ever been seen during a Censys scan
POST /v1/search/certificates
Body
{ "query": "parsed.names: censys.io and parsed.signature.self_signed: true and metadata.seen_in_scan: true", "page": 1, "fields": [ "parsed.fingerprint_sha256" ], "flatten": true }
Example Response
The response includes the first of 50 pages of the fingerprints whose certificates matched the query.
{ "status": "ok", "metadata": { "query": "parsed.names: censys.io and parsed.signature.self_signed: true and metadata.seen_in_scan: true", "count": 4974, "backend_time": 37, "page": 1, "pages": 50 }, "results": [ { "parsed.fingerprint_sha256": "6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01" }, { "parsed.fingerprint_sha256": "983efe28bf271a8cc5c482f92a762146dedbbcbaec76f11558c6cee2aeb3954b" }, { "parsed.fingerprint_sha256": "e0dd3fb5cf70c3efac9fbbf5f05d2726e90d18193ed7e2a099dde2f9a906ea87" }, ... ] }
View a Certificate
View individual certificate records, which include the raw bytes, parsed fields, certificate transparency data, browser trust, and metadata about Censys’s discovery of the certificate and maintenance of its record.
Method and URL
GET v1/view/certificates/{fp}
URL Parameters
Parameter | Required? | Type | Description | Example |
---|---|---|---|---|
fp |
required |
string |
The SHA-256 fingerprint of the cert |
|
Query Parameters
None
Example View Request
View the Censys record of the certificate fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70.
GET https://search.censys.io/api/v1/view/certificates/fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70
Example Response
The certificate record was successfully retrieved.
{ "validation_timestamp": "2015-10-07T01:18:48+00:00", "updated_at": "2015-10-06T20:18:50", "raw": "MIIDQ\...G9rw=", "validation.nss.valid": false, "parsed": { "fingerprint_sha1": "3704a663ed5db89f85c5377852d678b299389775", "subject_dn": "CN=ns1.google.com, emailAddress=ssl@ns1.google.com", "issuer": { "common_name": [ "ns1.google.com" ] }, "signature": { "self_signed": true, "valid": false, "value": "Leve...dvA==", "signature_algorithm": { "oid": "1.2.840.113549.1.1.11", "name": "SHA256WithRSA" } }, "validity": { "start": "2015-09-10T06:49:19Z", "end": "2016-09-09T06:49:19Z" }, "issuer_dn": "CN=ns1.google.com, emailAddress=ssl@ns1.google.com", "fingerprint_sha256": 20 "fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70", "version": 3, "extensions": { "authority_key_id": "dc3e2e3f49b126782f2dd4444c3cb5970be85979", "basic_constraints": { "is_ca": false }, "subject_key_id": "3D4uP0mxJngvLdRETDy1lwvoWXk=", "certificate_policies": [ ] }, "signature_algorithm": { "oid": "1.2.840.113549.1.1.11", "name": "SHA256WithRSA" }, "serial_number": "1952809538", "fingerprint_md5": "37ec912bf30802fd4ab3592f8713ef6f", "subject_key_info": { "key_algorithm": { "oid": "", "name": "RSA" }, "rsa_public_key": { "length": 2048, "modulus": "vYjm5...PfLw==", "exponent": 65537 } }, "subject": { "common_name": [ "ns1.google.com" ] } }, }
Comments
0 comments
Article is closed for comments.