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": 290406670, // Total number of services whose TLS values were tallied "buckets": [ { "key": "TLSv1_2", "count": 77335713 }, { "key": "TLSv1_3", "count": 53386055 }, { "key": "TLSv1_0", "count": 2937331 }, { "key": "TLSv1_1", "count": 615279 } ], "total_omitted": 0, // The number of services 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.
The preview can be configured using the fields
parameter, which takes a list of up to 25 fields to be returned for each host, although some fields with large values (e.g., services.banner
and services.http.response.body
) are not allowed.
If no fields
are submitted, default fields will be returned.
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 hits to be returned in a page (max: 100, default: 50) |
|
cursor |
optional |
string |
The base-64-encoded string of the next or prev page cursor returned in the API response |
|
fields |
optional |
string |
A list of up to 25 comma-separated host field names in dot-delimited notation to return for each hit in the result. |
|
Example Search Request
Search for hosts with an HTTP service reporting nginx in the server header, with at least some additional characters following the exact word, and for each hit, return the server header and any identified software packages in CPE format.
GET https://search.censys.io/api/v2/hosts/search?q=services.http.response.headers.server%3A%20nginx%3F%2A&per_page=1&virtual_hosts=EXCLUDE&fields=services.port%2Cservices.service_name%2Cservices.software.uniform_resource_identifier
Example Success Response
The search executed successfully and found 6,066,475 hosts matching the query.
One hit, as specified by the per_page
parameter, is printed out with the fields specified in the fields
parameter.
{ "code": 200, "status": "OK", "result": { "query": "services.http.response.headers.server: nginx?*", "total": 6066475, "duration": 551, "hits": [ { "services": [ { "service_name": "HTTP", "software": [ { "uniform_resource_identifier": "cpe:2.3:o:microsoft:windows:*:*:*:*:*:*:*:*" }, { "uniform_resource_identifier": "cpe:2.3:a:microsoft:http_api:2.0:*:*:*:*:*:*:*" } ], "port": 5985 }, { "software": [ { "uniform_resource_identifier": "cpe:2.3:a:f5:nginx:1.1:*:*:*:*:*:*:*" } ], "service_name": "HTTP", "port": 19999 }, { "software": [ { "uniform_resource_identifier": "cpe:2.3:o:microsoft:windows:*:*:*:*:*:*:*:*" }, { "uniform_resource_identifier": "cpe:2.3:a:microsoft:http_api:2.0:*:*:*:*:*:*:*" } ], "port": 47001, "service_name": "HTTP" } ], "ip": "1.194.187.56", "matched_services": [ { "service_name": "HTTP", "extended_service_name": "HTTP", "transport_protocol": "TCP", "port": 19999 } ] } ], "links": { "next": "eyJ2ZXJzaW9uIjoxLCJzb3J0IjpbeyJfc2NvcmUiOnsib3JkZXIiOiJkZXNjIn19LHsiaXAiOnsib3JkZXIiOiJhc2MiLCJtb2RlIjoibWluIiwibWlzc2luZyI6Il9sYXN0In19LHsibmFtZS5fX3JhdyI6eyJvcmRlciI6ImFzYyIsIm1vZGUiOiJtaW4iLCJtaXNzaW5nIjoiX2xhc3QifX1dLCJzZWFyY2hfYWZ0ZXIiOlsyLjAsIjEuMTk0LjE4Ny41NiIsbnVsbF0sInJldmVyc2VkIjpmYWxzZX0=", "prev": "" } } }
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" } }
Certificate Records
Certificate records are identified by a SHA-256 digest of their content (referred to as a fingerprint
or fp
).
Search for, view certificates, 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.
A sampling of endpoints that take the HTTP GET
method:
-
Hosts by Cert (
v2/certificates/{fp}/hosts
) — Lists the hosts that are currently presenting a certificate. -
Search (
v2/certificates/search
) — Search for hosts using the Censys Search Language. -
Report (
v2/certificates/aggregate
) — Generate a report about the values for a specified field across all certs matching a search. -
View (
v2/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 6acc…3e01.
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
GET v2/certificates/search
OR
POST v2/certificates/search
URL Parameters
None
Query Parameters
None
Data Parameters
Data parameters should be posted as a JSON request document if using the POST
method or should be added as query parameters to the path if using the GET
method.
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
Request 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, trust and revocation status, and information about Censys' maintenance of each record.
Method and URL
GET v2/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 fce6…2f70.
GET https://search.censys.io/api/v1/view/certificates/fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70
Example Response
The certificate record was successfully retrieved.
{ "code": 200, "status": "OK", "result": { "_encoding": { "fingerprint_sha256": "DISPLAY_HEX", "fingerprint_sha1": "DISPLAY_HEX", "fingerprint_md5": "DISPLAY_HEX", "tbs_fingerprint_sha256": "DISPLAY_HEX", "tbs_no_ct_fingerprint_sha256": "DISPLAY_HEX", "spki_fingerprint_sha256": "DISPLAY_HEX", "raw": "DISPLAY_BASE64" }, "fingerprint_sha256": "fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70", "fingerprint_sha1": "3704a663ed5db89f85c5377852d678b299389775", "fingerprint_md5": "37ec912bf30802fd4ab3592f8713ef6f", "tbs_fingerprint_sha256": "e9bae1d0af98bfebcb73d061e2b5088d33ecf4e29646b5afbcc9b0026f9f8641", "tbs_no_ct_fingerprint_sha256": "e9bae1d0af98bfebcb73d061e2b5088d33ecf4e29646b5afbcc9b0026f9f8641", "spki_fingerprint_sha256": "28359cf3792cf85e8aca5cb9f3eaf6b37c1784892b9782100e8df47568201af8", "parsed": { "version": 3, "serial_number": "1952809538", "issuer_dn": "emailAddress=ssl@ns1.google.com, CN=ns1.google.com, emailAddress=ssl@ns1.google.com", "issuer": { "common_name": [ "ns1.google.com" ], "email_address": [ "ssl@ns1.google.com" ] }, "subject_dn": "emailAddress=ssl@ns1.google.com, CN=ns1.google.com, emailAddress=ssl@ns1.google.com", "subject": { "common_name": [ "ns1.google.com" ], "email_address": [ "ssl@ns1.google.com" ] }, "subject_key_info": { "key_algorithm": { "name": "RSA", "oid": "1.2.840.113549.1.1.1" }, "rsa": { "exponent": 65537, "_encoding": { "modulus": "DISPLAY_HEX" }, "modulus": "bd88e6e591887449355a8edba1d9c9b2228d8aa3d9a04b145eaa0357e4c6a48c4264a906077a09b1ca0768362e6d505416eb9cfbafd3b43dfbd6111623c68c84f03f421441b59b8a0d7532808807cb5f12046d9c8896fbc5c44805d3bd14d9aca5f971157e682cf6d573e2e35cfcf90acd49ddd012aa1f900d68dd76f98c69183a53ea101e644e62addba3e363945f8f15ce9727ecee83d543129a4d2a1be0c3cdd814e692fa895b28bbacdf84f15b60b5ed0d2af0005ab27dc60dfa7e3b98b164791f30953582bb2b419476f681e4802e78372b4e1618968cba12b25618e6215944f9c3af81ad199cd79ab6573f0c22354a88da86ae67c9b4dad6b20843df2f", "length": 2048 }, "_encoding": { "fingerprint_sha256": "DISPLAY_HEX" }, "fingerprint_sha256": "5cbcb9740f3d8a447d4267722092ad405701c6036d93b1a84c512ebefbcbe346", "_key": "rsa" }, "validity_period": { "not_before": "2015-09-10T06:49:19Z", "not_after": "2016-09-09T06:49:19Z", "length_seconds": 31536000 }, "signature": { "signature_algorithm": { "name": "SHA256-RSA", "oid": "1.2.840.113549.1.1.11" }, "_encoding": { "value": "DISPLAY_HEX" }, "value": "2debde1ae43b9d585fb0217c35fab2b7a69aef4a40c1d87293101c2accb27d92117a8b6165b87defda6c47d9d800e91bb1bf73c4debdce5abb20447c450c7a3e9970e3d07871255dcfaff3155d515c2628d95661557a6f414c4fd533b750cfdc2eac1675d44735f9b425637f5af611fe4350f819ad88aa995163675ac2a154d9e849efcbba46dc65abc03e963edc79058913d323d69f7f11519e61637532c79670d73605aab63ac4404df03fa1bdf165c0a2189ff8280ff7a85ba1ed6aed8224af32a06d168ca097ad2406a19f0f46739f6766068a876d3925e46714cd5e78e07f8b11577b590ff0248019ee4191dfb6d4dbd4a179764de5a4d3063659c6f6bc", "self_signed": true, "valid": false }, "extensions": { "basic_constraints": { "is_ca": false }, "_encoding": { "authority_key_id": "DISPLAY_HEX", "subject_key_id": "DISPLAY_HEX" }, "authority_key_id": "dc3e2e3f49b126782f2dd4444c3cb5970be85979", "subject_key_id": "dc3e2e3f49b126782f2dd4444c3cb5970be85979", "ct_poison": false }, "redacted": false }, "names": [ "ns1.google.com" ], "validation": { "nss": { "type": "LEAF", "is_valid": false, "ever_valid": false, "has_trusted_path": false, "had_trusted_path": false, "in_revocation_set": false }, "microsoft": { "type": "LEAF", "is_valid": false, "ever_valid": false, "has_trusted_path": false, "had_trusted_path": false, "in_revocation_set": false }, "apple": { "type": "LEAF", "is_valid": false, "ever_valid": false, "has_trusted_path": false, "had_trusted_path": false, "in_revocation_set": false }, "google_ct_primary": { "type": "LEAF", "is_valid": false, "ever_valid": false, "has_trusted_path": false, "had_trusted_path": false, "in_revocation_set": false }, "chrome": { "type": "LEAF", "is_valid": false, "ever_valid": false, "has_trusted_path": false, "had_trusted_path": false, "in_revocation_set": false } }, "ever_seen_in_scan": true, "raw": "MIIDQzCCAiugAwIBAgIEdGWCQjANBgkqhkiG9w0BAQsFADA8MRcwFQYDVQQDDA5uczEuZ29vZ2xlLmNvbTEhMB8GCSqGSIb3DQEJARYSc3NsQG5zMS5nb29nbGUuY29tMB4XDTE1MDkxMDA2NDkxOVoXDTE2MDkwOTA2NDkxOVowPDEXMBUGA1UEAwwObnMxLmdvb2dsZS5jb20xITAfBgkqhkiG9w0BCQEWEnNzbEBuczEuZ29vZ2xlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL2I5uWRiHRJNVqO26HZybIijYqj2aBLFF6qA1fkxqSMQmSpBgd6CbHKB2g2Lm1QVBbrnPuv07Q9+9YRFiPGjITwP0IUQbWbig11MoCIB8tfEgRtnIiW+8XESAXTvRTZrKX5cRV+aCz21XPi41z8+QrNSd3QEqofkA1o3Xb5jGkYOlPqEB5kTmKt26PjY5RfjxXOlyfs7oPVQxKaTSob4MPN2BTmkvqJWyi7rN+E8Vtgte0NKvAAWrJ9xg36fjuYsWR5HzCVNYK7K0GUdvaB5IAueDcrThYYloy6ErJWGOYhWUT5w6+BrRmc15q2Vz8MIjVKiNqGrmfJtNrWsghD3y8CAwEAAaNNMEswHQYDVR0OBBYEFNw+Lj9JsSZ4Ly3UREw8tZcL6Fl5MB8GA1UdIwQYMBaAFNw+Lj9JsSZ4Ly3UREw8tZcL6Fl5MAkGA1UdEwQCMAAwDQYJKoZIhvcNAQELBQADggEBAC3r3hrkO51YX7AhfDX6sremmu9KQMHYcpMQHCrMsn2SEXqLYWW4fe/abEfZ2ADpG7G/c8Tevc5auyBEfEUMej6ZcOPQeHElXc+v8xVdUVwmKNlWYVV6b0FMT9Uzt1DP3C6sFnXURzX5tCVjf1r2Ef5DUPgZrYiqmVFjZ1rCoVTZ6Envy7pG3GWrwD6WPtx5BYkT0yPWn38RUZ5hY3Uyx5Zw1zYFqrY6xEBN8D+hvfFlwKIYn/goD/eoW6Htau2CJK8yoG0WjKCXrSQGoZ8PRnOfZ2YGiodtOSXkZxTNXnjgf4sRV3tZD/AkgBnuQZHfttTb1KF5dk3lpNMGNlnG9rw=", "added_at": "1970-01-01T00:00:00Z", "modified_at": "2023-02-15T00:48:29Z", "validated_at": "2023-01-25T22:44:06Z", "zlint": { "version": 3, "timestamp": "2023-02-15T00:48:29Z", "notices_present": true, "errors_present": true, "failed_lints": [ "e_ext_san_missing", "e_sub_cert_aia_does_not_contain_ocsp_url", "e_sub_cert_aia_missing", "e_sub_cert_cert_policy_empty", "e_sub_cert_certificate_policies_missing", "e_sub_cert_eku_missing", "e_subject_common_name_not_from_san", "n_subject_common_name_included" ], "warnings_present": false, "fatals_present": false }, "precert": false, "revoked": false, "validation_level": "UNKNOWN", "parse_status": "CERTIFICATE_PARSE_STATUS_UNKNOWN", "labels": [ "never-trusted", "untrusted", "leaf", "ct", "expired", "self-signed" ] } }
Comments
0 comments
Article is closed for comments.