Censys Getting Started: API Access and First Request (2026)

Getting started overview

To begin using Censys programmatically for external attack surface management or internet-wide scanning, the core process involves setting up an account, obtaining API credentials, and then executing a query. Censys offers a REST API that allows developers to integrate its capabilities into custom applications and security workflows. The platform provides official SDKs for Python and Go, which abstract the underlying HTTP requests, simplifying interaction with the API. Direct HTTP requests using tools like cURL are also supported for all API endpoints.

The Censys API provides access to various functionalities, including searching internet scan data (Censys Search) and managing assets within your organization's attack surface (Censys Attack Surface Management). Understanding the data structures returned by the API, typically in JSON format, is crucial for effective integration. For detailed information on the available endpoints and data models, refer to the Censys API reference documentation.

Here's a quick reference table outlining the initial steps:

Create an account and get keys

Before making any API calls, you need a Censys account. Censys offers a Censys Search Community Edition that provides free access with certain usage limits, suitable for initial exploration and development. For advanced features, higher query limits, or external attack surface management, commercial plans like Censys ASM Essentials are available, starting at $5,000 annually.

1. Register for an account: Navigate to the Censys website and sign up. You will typically use your email address to create an account.

2. Access API Credentials: Once logged in, your API credentials (API ID and API Secret) can be found in your account settings or profile section. These keys are essential for authenticating your API requests. Treat your API Secret like a password and keep it secure to prevent unauthorized access to your Censys account and data.

   Censys uses API key authentication. Each request to the API requires both your API ID and API Secret to be included in the request headers or body, depending on the specific endpoint and method. The Censys API documentation provides specific examples for how to include these credentials.

Your first request

After obtaining your API ID and Secret, you can make your first API request. This example uses the Censys Search API to query for hosts. Replace YOUR_CENSYS_API_ID and YOUR_CENSYS_API_SECRET with your actual credentials.

Using cURL (HTTP Request)

A cURL request directly demonstrates the HTTP interaction. This example performs a basic search for hosts running web services on port 80.

curl -X POST \ 
  'https://search.censys.io/api/v2/search/hosts' \ 
  -H 'Content-Type: application/json' \ 
  -H 'Accept: application/json' \ 
  -u 'YOUR_CENSYS_API_ID:YOUR_CENSYS_API_SECRET' \ 
  -d '{ "q": "services.port:80 and tags:"http"", "per_page": 1 }'

This command sends a POST request to the Censys hosts search endpoint, authenticating with your API ID and Secret. The -d flag specifies the JSON payload containing your search query (q) and the number of results per page (per_page).

Using Python SDK

First, install the Censys Python SDK:

pip install censys

Then, use the following Python code. This example performs a similar search for hosts on port 80.

import os
from censys.search import CensysSearch

# Set your API ID and Secret as environment variables or replace directly
CENSYS_API_ID = os.environ.get("CENSYS_API_ID", "YOUR_CENSYS_API_ID")
CENSYS_API_SECRET = os.environ.get("CENSYS_API_SECRET", "YOUR_CENSYS_API_SECRET")

# Initialize the Censys Search client
c = CensysSearch(api_id=CENSYS_API_ID, api_secret=CENSYS_API_SECRET)

# Perform a host search
try:
    # The search method returns an iterator, get the first page of results
    hosts = c.hosts.search("services.port:80 and tags:\"http\"", per_page=1)
    for host in hosts:
        print(host)
except Exception as e:
    print(f"An error occurred: {e}")

This Python script initializes the CensysSearch client with your credentials and then calls the hosts.search method. It's recommended to store API keys as environment variables for security, as shown in the example.

Using Go SDK

First, install the Censys Go SDK:

go get github.com/censys/censys-go/search

Then, use the following Go code to perform a host search:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/censys/censys-go/search"
)

func main() {
	// Set your API ID and Secret as environment variables or replace directly
	apiID := os.Getenv("CENSYS_API_ID")
	apiSecret := os.Getenv("CENSYS_API_SECRET")

	if apiID == "" || apiSecret == "" {
		fmt.Println("Error: CENSYS_API_ID and CENSYS_API_SECRET environment variables must be set.")
		return
	}

	client := search.NewClient(nil)
	client.Auth(apiID, apiSecret)

	query := "services.port:80 and tags:\"http\""
	options := &search.SearchOptions{PerPage: 1}

	hosts, _, err := client.SearchHosts(context.Background(), query, options)
	if err != nil {
		fmt.Printf("Error searching hosts: %v\n", err)
		return
	}

	for _, host := range hosts.Result.Hits {
		fmt.Printf("Host: %s\n", host.IP)
	}
}

This Go example sets up the Censys client, authenticates with environment variables, and then uses client.SearchHosts to execute the query. Error handling is included to manage potential issues during the API call.

Common next steps

After successfully making your first API call, consider these next steps:

• Explore additional endpoints: The Censys API offers various endpoints for different data types, including hosts, certificates, and autonomous systems. Review the Censys API reference documentation to understand the full range of data you can access and the queries you can construct.

• Refine your queries: Censys uses its own query language. Familiarize yourself with the syntax and available fields to build more specific and powerful searches. The Censys Search Query Language documentation provides comprehensive details.

• Integrate into workflows: Integrate Censys data into your existing security tools, dashboards, or automation scripts. This might involve ingesting data into SIEM systems, vulnerability management platforms, or threat intelligence platforms.

• Understand rate limits and pagination: Be aware of API rate limits to avoid being blocked. For large datasets, implement pagination to retrieve results in manageable chunks. Details on these operational aspects are available in the Censys API documentation.

• Explore Censys Attack Surface Management (ASM): If your organization needs to monitor and manage its external digital footprint, explore the ASM capabilities. This involves defining your organization's assets and continuously monitoring them for changes and vulnerabilities. The Censys ASM documentation provides guidance on this product.

Troubleshooting the first call

If your first API call fails, consider the following common issues and solutions:

• Incorrect API Credentials: Double-check your API ID and API Secret for typos. Ensure they are correctly placed in the authentication header or parameters as required by the SDK or cURL command. An expired or revoked key will also result in authentication failures. For example, the OAuth 2.0 specification outlines common client authentication methods, which, while not directly applicable to Censys's API key model, highlight the importance of correct credential handling across various API systems, as detailed in the OAuth 2.0 client authentication methods documentation.

• Rate Limiting: If you are making too many requests in a short period, you might hit a rate limit. The API will typically return an HTTP 429 Too Many Requests status code. Implement delays between requests or review your usage patterns.

• Network Connectivity: Verify that your machine has internet access and can reach search.censys.io. Firewall rules or proxy settings might interfere with the connection.

• Incorrect Endpoint or Method: Ensure you are using the correct URL for the API endpoint (e.g., /api/v2/search/hosts) and the appropriate HTTP method (e.g., POST for search). Refer to the Censys API reference for specific endpoint details.

• Invalid Query Syntax: If your search query (q parameter) is malformed, the API might return an error related to parsing the query. Consult the Censys Search Query Language documentation for correct syntax.

• JSON Payload Errors: For POST requests, ensure your JSON request body is correctly formatted. Missing commas, unquoted keys, or incorrect data types can lead to errors. Tools like jq can help validate JSON syntax locally.