The Censys REST API provides programmatic access to the same data accessible through the web interface. API access is governed by our Terms of Service and all scripted access should use this API. We list our API endpoints below.


All API endpoints are hosted at https://censys.io/api/v1/ and require authenticating with HTTP basic auth using the API ID and secret that are shown under My Account. This page also lists the rate limits that apply to your account.

API Endpoints

We provide the following API endpoints:

The search endpoint allows searches against the IPv4, Alexa Top Million, and Certificates indexes using the same search syntax as the main site. The endpoint returns a paginated result of the most recent information we know for the set of user selected fields. More information about the returned hosts, websites, and certificates can be fetched using the /view endpoint.
The view endpoint fetches the structured data we have about a specific host, website, or certificate once you know the host's IP address, website's domain, or certificate's SHA-256 fingerprint.
The bulk endpoint fetches the structured data we have about certificates in bulk, once you know the certificate's SHA-256 fingerprints.
The report endpoint allows you to determine the aggregate breakdown of a value for the results a query, similar to the "Build Report" functionality available in the primary search interface. For example, if you wanted to determine the breakdown of cipher suites selected by all websites in the Top Million.
The data endpoint exposes metadata on raw data that can be downloaded from Censys. For example, if you wanted to determine whether a new dataset has been posted in a given series and how to download it.
The account endpoint returns information about your Censys account, most notably including your current query quota usage.


REST Access (Raw Data). Below is a sample Python script that connects to the API and lists raw datasets that are available for download.

import sys
import requests

API_URL = "https://censys.io/api/v1"
UID = "login for API key"
SECRET = "login for API secret"

res = requests.get(API_URL + "/data", auth=(UID, SECRET))
if res.status_code != 200:
    print("error occurred: %s" % res.json()["error"])
for name, series in res.json()["raw_series"].items():
    print(series["name"], "was last updated at", series["latest_result"]["timestamp"])

Censys Python Library. We also maintain a Python library for interacting with the API, which can be installed with Pip: pip install censys.
Below is a sample script that iterates over NSS trusted certificates:

import censys.certificates

UID = "login for API key"
SECRET = "login for API secret"

certificates = censys.certificates.CensysCertificates(UID, SECRET)
fields = ["parsed.subject_dn", "parsed.fingerprint_sha256", "parsed.fingerprint_sha1"]

for c in certificates.search("validation.nss.valid: true", fields=fields):