The Censys Platform API provides programmatic access to the data available in the Censys Platform. The Platform API is organized around RESTful principles and follows a predictable, resource-oriented URL structure, supports application/JSON request bodies, returns JSON-encoded responses, and adheres to standard HTTP methods, authentication, and response codes.
API access is governed by the Censys Terms of Service and all scripted access should use this API. Your API rate limits are shown on the Censys Platform Personal Access Tokens page.
Before you begin: usage and data access
- The API is available for Starter and Enterprise tiers, but not for Free tier users.
- API calls consume credits, just like actions in the Platform UI. The number of credits used by an API request corresponds to the same actions performed in the UI, such as executing searches. For more information, see Censys Credits.
- API usage aligns with the data access capacity of your tier. For example, the Starter tier can view one week of host history while the Enterprise tier can view one month of history. For more information, see Data Access Tiers and Entitlements.
Transition from Legacy API
The Platform now includes a new API. To ensure a smooth transition, please update the following:
- Base URL: There is a new base URL for the Censys Platform API.
- Access token: There is a new process to generate a Personal Access Token.
- Review any downstream applications that receive data from the API.
Quick start
Follow the steps below to begin using the Censys API.
Step 1: API Access Role
To use the Platform API, you must be assigned the API Access Role. To learn more about roles, see Role-Based Access Control.
Step 2: Authenticate with a Personal Access Token
The Censys Platform API uses Personal Access Tokens to authenticate requests. Users can generate multiple PATs as needed.
-
Go to My Account > Personal Access Tokens tab.
-
Click Create New Token.
-
Name your PAT in the Token Name field (Required) and add a description (Optional).
-
Click Create.
-
A confirmation dialog appears when the token is successfully created. Click Copy to clipboard and store your token in a secure location for future use. The token value is found at the bottom of the dialog.
Warning
Your Personal Access Tokens grant significant access, so keep them secure. Never expose API keys in public areas like GitHub or client-side code.
Delete a Personal Access Token
Follow the steps below to delete a token:
-
Go to My Account > Personal Access Tokens tab.
-
Locate the token that you want to delete.
-
Click the trash can icon on the token card.
-
The token is deleted.
Step 3: Set your Organization ID
The Censys Platform API identifies the entitlements and billing details for your request based on the provided Organization ID. To locate your Organization ID:
- Go the the Censys Platform.
- Click on My Account.
- The Organization ID is located in the URL.

Note
The Organization ID can be set via query parameter or header. If values are provided for both, the query parameter takes precedence. An Organization ID must be provided for each request to the API.
Header
After you identify your Organization ID, you can include it in the header or as a query parameter.
--header 'X-Organization-ID: c486f89f-8e4d-4c7a-830d-8d1d5b822c20'
Query Parameter
organization_id=c486f89f-8e4d-4c7a-830d-8d1d5b822c20
Step 4: Understand Headers
You can include the following headers when making requests to the Censys Platform API.
Personal Access Token (PAT) (Required)
You must include a valid PAT to make API requests. Use the format below to set your PAT in the header.
--header 'Authorization: Bearer censys_1AW2vmJf_Q8849MHxQiQZwZEattrJK9wL'
Organization ID (Optional)
You can set your Organization ID in the header or in the query parameters, but it is required in one of these fields. Use the format below to set your Organization ID as a header.
--header 'X-Organization-ID: c486f89f-8e4d-4c7a-830d-8d1d5b822c20'
Accept (Optional)
The Accept header uses a vendor-specific content type, which specifies both the desired response format (JSON) and the version of the asset schema (host, certificate, web property) the client expects to receive. This allows users to explicitly request a compatible schema version, even as the API and data models evolve over time.
If you don't include this header, your call will return the most recent schema version. Currently, there is one schema version available.
Format
Use the format below to create a valid Accept header.
application/vnd.censys.api.{api_version}.{asset_name}.{asset_version}+json
The example below is the Accept header for the Asset / Host endpoint.
Accept: application/vnd.censys.api.v3.host.v1+json
Explanation
This example above requests the following:
- API Version: v3
- Asset Type: host
- Schema Version: v1
- Format: json
Step 5: Make API calls
After you create a PAT, you can start making API calls using cURL, Postman, or the Try It feature on the reference documentation page. The Censys Platform API typically follows standard HTTP response codes to indicate whether a request was successful or failed.
Example cURL API call
The example cURL request below is for Asset / Host endpoint. This call includes the Organization ID as a query parameter.
curl --request GET \
--url 'https://api.platform.censys.io/v3/global/asset/host/47.33.210.14?organization_id=c486f89f-8e4d-4c7a-830d-8d1d5b822c20' \
--header 'Accept: application/vnd.censys.api.v3.host.v1+json' \
--header 'Authorization: Bearer censys_1AW2vmJf_Q8849MHxQiQZwZEattrJK9wL'
The cURL request below includes the Organization ID in the header.
curl --request GET \
--url 'https://api.platform.censys.io/v3/global/asset/host/47.33.210.14' \
--header 'X-Organization-ID: c486f89f-8e4d-4c7a-830d-8d1d5b822c20' \
--header 'Accept: application/vnd.censys.api.v3.host.v1+json' \
--header 'Authorization: Bearer censys_1AW2vmJf_Q8849MHxQiQZwZEattrJK9wL'
Example response
Click the header below to view an example response.
Example Response
{
"result": {
"resource": {
"ip": "27.33.219.14",
"location": {
"continent": "North America",
"country": "United States",
"country_code": "US",
"city": "Mount Pleasant",
"postal_code": "48858",
"timezone": "America/Detroit",
"province": "Michigan",
"coordinates": {
"latitude": 43.59781,
"longitude": -84.76751
}
},
"autonomous_system": {
"asn": 20115,
"description": "ACME-20115",
"bgp_prefix": "47.33.192.0/19",
"name": "ACME-20115",
"country_code": "US"
},
"whois": {
"network": {
"handle": "AC04",
"name": "Acme",
"cidrs": [
"47.32.0.0/12",
"47.48.0.0/14"
],
"created": "2014-12-23T00:00:00Z",
"updated": "2014-12-23T00:00:00Z",
"allocation_type": "ALLOCATION"
},
"organization": {
"handle": "CC04",
"name": "Acme",
"street": "6175 S. Willow Dr",
"city": "Greenwood Village",
"state": "CO",
"postal_code": "80111",
"country": "US",
"abuse_contacts": [
{
"handle": "ABUSE19-ARIN",
"name": "Abuse",
"email": "[email protected]"
}
],
"admin_contacts": [
{
"handle": "IPADD1-VRIN",
"name": "IPAddressing",
"email": "[email protected]"
}
],
"tech_contacts": [
{
"handle": "IPADD1-VRIN",
"name": "IPAddressing",
"email": "[email protected]"
}
]
}
},
"services": [
{
"port": 7547,
"protocol": "CWMP",
"transport_protocol": "tcp",
"ip": "47.24.210.14",
"scan_time": "2025-03-06T19:03:55Z",
"banner_hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"cwmp": {
"auth": [
"Digest realm=\"Sagemcom TR-069\", qop=\"auth,auth-int\", nonce=<REDACTED>, opaque=\"ddb504c1\""
],
"server": "gSOAP/2.7"
}
}
],
"service_count": 1,
"dns": {
"reverse_dns": {
"resolve_time": "2025-02-13T14:02:41Z",
"names": [
"syn-047-033-210-014.res.acme.com"
]
},
"names": [
"syn-047-033-210-014.res.spectrum.com"
],
"forward_dns": {
"syn-047-033-210-014.res.acme.com": {
"resolve_time": "2025-02-27T20:21:52Z",
"name": "syn-047-033-210-014.res.acme.com",
"record_type": "a"
}
}
}
},
"extensions": {}
}
}
Step 6: Handle HTTP response codes
Error Code | Description | Resolution |
---|---|---|
200 | OK - Your call was successful. | Success |
401 | Your request doesn't contain a valid Authorization token. | Verify whether you used the correct PAT or generate a new PAT. |
403 | User does not have permission to access this data. | Ask your admin to grant you API Access Role. Verify that your user tier offers the data requested. |
404 | Not Found | Insufficient permissions for the resource; it could be a resource from a different org, etc. |
422 | Unprocessable Entity | Misconfigured or incorrect value. Some examples: incompatible search filters, malformed query string, invalid pagination parameters etc. |
422 | Missing Organization ID | Enter a valid Organization ID as a query parameter or in the header. |
422 | Unprocessable Entity | Enter a valid query parameter. |
500 | Internal Server | General issue, try again later. |
Next steps
API rate limits
Rate limits are associated with your account tier.
Tier | Concurrent Actions |
---|---|
Free | No API access |
Starter | 1 concurrent action |
Enterprise | 10 concurrent actions |
Base URL
Before making requests, use the following Base URL for Global Data Endpoints:
https://api.platform.censys.io/v3/global/
All API requests to Global Data endpoints must be sent to this base URL, with the appropriate endpoint appended.
The base URL for Collections API is:
https://api.platform.censys.io/v3/collections/