--- title: Censys API Integration on Truto slug: censys category: Security canonical: "https://truto.one/integrations/detail/censys/" --- # Censys API Integration on Truto **Category:** Security **Status:** Generally available ## MCP-ready AI tools Truto exposes 47 tools for Censys that AI agents can call directly. - **get_single_censys_host_by_id** — Get a single Censys host by its IP address. Returns: ip, location, autonomous_system, whois, services, service_count, dns. Required: id (the host's IP address). - **censys_hosts_bulk_get** — Retrieve up to 100 Censys hosts by their IP addresses in a single POST request. Returns: resource, extensions. Required: host_ids. - **list_all_censys_hosts** — Retrieve multiple Censys hosts by their IP addresses via the deprecated GET method. Returns: resource, extensions. Required: host_ids. Use the bulk_get POST variant instead. - **censys_hosts_enrichment** — Get enrichment data for a single Censys host by IP address. Returns: ip, location, autonomous_system, whois, services, service_count, dns, reputation, greynoise, network, privacy, labels, third_party. Required: host_ip. - **censys_hosts_event_history** — Get event history timeline for a Censys host. Returns: resource, extensions. Required: host_id, start_time, end_time. start_time is the timestamp closest to current time and end_time is furthest; both must be valid RFC3339 strings. - **censys_hosts_service_history** — Get historical service observations for a Censys host by IP address. Returns the host resource including ip, location, autonomous_system, whois, services (port, protocol, transport_protocol, scan_time, banner_hash_sha256), service_count, dns, and extensions. Required: host_id, organization_id. Max 100 results per page. - **get_single_censys_certificate_by_id** — Get a single Censys certificate by its SHA-256 fingerprint. Returns: fingerprint_sha256, fingerprint_sha1, fingerprint_md5, tbs_fingerprint_sha256, tbs_no_ct_fingerprint_sha256, spki_subject_fingerprint_sha256, parent_spki_subject_fingerprint_sha256, parsed, precert, revoked, names, validation_level, validation, revocation, ct, ever_seen_in_scan, raw, added_at, modified_at, validated_at,… - **censys_certificates_raw** — Get the raw PEM-encoded content of a Censys certificate by its SHA-256 fingerprint. Returns the raw PEM-encoded certificate string. Required: certificate_id. - **censys_certificates_bulk_get** — Retrieve multiple Censys certificates by their SHA-256 fingerprints in a single request. Returns: fingerprint_sha256, fingerprint_sha1, fingerprint_md5, tbs_fingerprint_sha256, tbs_no_ct_fingerprint_sha256, spki_subject_fingerprint_sha256, parent_spki_subject_fingerprint_sha256, parsed, precert, revoked, names, validation_level, validation, revocation, ct, ever_seen_in_scan, raw, added_at,… - **list_all_censys_certificates** — Retrieve multiple Censys certificates by their SHA-256 fingerprints. Deprecated GET variant; use the POST endpoint for new integrations. Returns: fingerprint_sha256, fingerprint_sha1, fingerprint_md5, tbs_fingerprint_sha256, tbs_no_ct_fingerprint_sha256, spki_subject_fingerprint_sha256, parent_spki_subject_fingerprint_sha256, parsed, precert, revoked, names, validation_level, validation,… - **censys_certificates_bulk_get_raw** — Retrieve up to 1,000 Censys certificates in raw PEM-encoded format by their SHA-256 fingerprints. Returns the PEM certificate content for each requested fingerprint. Required: certificate_ids. - **censys_certificates_list_raw** — Retrieve multiple Censys certificates in PEM format by their SHA-256 fingerprints. Returns: fingerprint_sha256, raw. Required: certificate_ids. The GET method is deprecated; prefer the POST variant. - **get_single_censys_web_property_by_id** — Get a single Censys web property by its hostname:port identifier. Returns: ip, location, autonomous_system, whois, services, service_count, dns. Required: id. - **censys_web_properties_bulk_get** — Retrieve multiple Censys web properties by identifier, up to 100 per call. Returns the result object with resource (ip, location, autonomous_system, whois, services, service_count, dns) and extensions. Required: webproperty_ids. - **list_all_censys_web_properties** — Retrieve multiple Censys web properties by identifier (deprecated GET method; prefer the POST bulk_get variant). Returns the result object with resource (ip, location, autonomous_system, whois, services, service_count, dns) and extensions. Required: webproperty_ids. - **censys_search_aggregate** — Aggregate Censys search results by a specified field, splitting values into term buckets with counts — the API equivalent of the Report Builder. Returns: buckets. Required: field, number_of_buckets, query. number_of_buckets must be between 1 and 2000. - **censys_search_convert** — Convert legacy Censys Search Language (CSL) queries to Platform (CenQL) queries in Censys. Returns the converted Platform query strings. Required: queries, organization_id. Limited to 100 queries per request. - **list_all_censys_search** — Search Censys global assets using a CenQL query string. Returns: host, matched_services. Required: query. Max 100 results per page. - **get_single_censys_scan_by_id** — Retrieve the status and result of a tracked scan in Censys by its scan ID. Returns: resource, extensions. The resource object contains host data including ip, location, autonomous_system, whois, services, service_count, and dns. Required: id, organization_id. - **censys_scans_rescan** — Initiate a live rescan of a known host service at ip:port or hostname:port in Censys. Returns a tracked scan result including scan_id and status, which can be polled via the Get scan status endpoint. Required: target, organization_id. - **censys_dns_ip_resolution_bounds** — Get DNS domain names that resolved to a specific IP address in Censys, with results aggregated per domain name. Returns a list of domain names that resolved to the provided IP, with aggregated time bounds per domain. Required: ip. - **censys_dns_ip_resolution_ranges** — Get DNS names that resolved to a specific IP in Censys with resolution records broken down by time range. Returns: ip, location, autonomous_system, whois, services, service_count, dns, extensions. Required: ip, organization_id. Max 100 results per page. - **censys_dns_name_resolution_bounds** — Get aggregated DNS resolution bounds for a domain name in Censys, showing currently resolving A, AAAA, MX, NS, SOA, and TXT records. Returns: name, record_type, resolve_time. Required: name, organization_id. - **censys_dns_name_resolution_ranges** — Get DNS resolution observations for a domain name in Censys, broken down by time range. Returns: name, record_type, resolve_time. Required: name, organization_id. - **list_all_censys_collections** — List all Censys collections for an organization, optionally filtered by collection status. Returns: collection_uid, name, description, query, status. - **get_single_censys_collection_by_id** — Get a single Censys collection by id. Returns: collection_uid, name, description, query, status. Required: id. - **create_a_censys_collection** — Create a new Censys collection with a name and CenQL query string. Returns: collection_uid, name, description, query, status. Required: name, query. - **update_a_censys_collection_by_id** — Update a Censys collection's name, description, and/or query by id. Returns the updated collection including its collection_uid, name, description, and query. Required: id, name, query. Cannot update a collection that is paused or archived. - **delete_a_censys_collection_by_id** — Delete a Censys collection by id. Returns an empty 204 response on success. Required: id. - **censys_collections_list_events** — List Censys collection events covering asset add/remove and status changes. Returns: asset_id, asset_type, collection_id, collection_name, event_type, evidence, org_id, query, timestamp, url. Required: collection_uid. - **censys_collections_aggregate** — Aggregate search results within a Censys collection by a specified field. Returns: buckets. Required: collection_uid, field, number_of_buckets, query. number_of_buckets must be between 1 and 2000. - **list_all_censys_censeye_jobs** — List CensEye pivot analysis jobs in Censys. Returns: job_id, status, target, created_at. Filter results by host_id, webproperty_id, or certificate_id. Required: organization_id. Max 100 per page. - **create_a_censys_censeye_job** — Create an async CensEye pivot analysis job in Censys for a host, web property, or certificate. Returns: job_id, status, target, created_at. Required: organization_id and target. The target must contain exactly one of host_id, webproperty_id, or certificate_id. Poll job status before fetching results. - **get_single_censys_censeye_job_by_id** — Get the status of a CensEye pivot analysis job in Censys. Poll this endpoint to check job completion before fetching results. Returns: resource, extensions. Required: id. - **censys_censeye_jobs_list_results** — List the results of a completed CensEye pivot analysis job in Censys. Returns: resource, extensions. Required: job_id. - **censys_censeye_value_counts** — Retrieve value counts in Censys to discover pivots by counting document matches for specific field-value pair groups filtered by an optional CenQL query. Returns count results under the result key for each requested group of field-value pairs. Required: organization_id, and_count_conditions. Each count-condition group may contain up to 5 field-value pairs. - **create_a_censys_discovery_scan** — Initiate a new Live Discovery scan in Censys by providing a target object. Returns the scan result object with discovery scan details. Required: target, organization_id. - **get_single_censys_organization_by_id** — Get a Censys organization's details by id, including member counts broken down by role and organization settings such as AI training and MFA requirements. Returns: created_at, member_counts, name, preferences, uid, organization_id, settings. Required: id. - **censys_organizations_list_members** — List members of a Censys organization with their full user details. Returns a paginated result where each member includes uid, email, first_name, last_name, roles, created_at, first_login_time, and latest_login_time, plus a pagination object containing next_page_token and page_size. Required: organization_id. - **censys_organizations_invite_user** — Invite a user to a Censys organization by email; the invited user receives an email to join. Returns an empty 201 response on success. Required: organization_id, email. - **censys_organizations_remove_member** — Remove a member from a Censys organization. Returns an empty 204 response on success. Required: organization_id, member_id. - **censys_organizations_credits** — Retrieve credit balance and expiration information for a Censys organization. Credits expire 12 months after they are acquired. Returns credit balance and expiration data. Required: organization_id. - **censys_organizations_credits_usage** — Get credit usage for a Censys organization over a specific date range. Returns: credits_consumed_by_consumer, credits_consumed_by_source, end_time, granularity, periods, start_time, total_added, total_consumed, total_expired, transaction_count. Required: organization_id, granularity. The date range cannot exceed 365 days and the earliest available date is 2025-01-01. - **censys_organizations_member_credits_usage** — Get credit consumption for a specific member of a Censys organization over a date range. Returns: credits_consumed_by_consumer, credits_consumed_by_source, end_time, granularity, periods, start_time, total_added, total_consumed, total_expired, transaction_count. Required: organization_id, user_id, granularity. The date range cannot exceed 365 days and the earliest available date is 2025-01-01. - **censys_users_credits** — Get the free user credit balance in Censys. Returns the credit balance result including a resource object with balance details and extensions. No required parameters. - **censys_users_credits_usage** — Get Censys user credit usage report broken down by daily or monthly granularity. Returns credit consumption data for the requested date range. Required: granularity. Dates must be on or after 2025-01-01 and the date range (end_date - start_date) cannot exceed 365 days. - **list_all_censys_search_collections** — Search for assets within a Censys collection by running a CenQL query across the collection's assets. Returns: host, matched_services. Required: collection_uid, query, organization_id. Max 100 results per page. ## How it works 1. **Link your customer's Censys account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Censys.** The Proxy API is a 1-to-1 mapping of the Censys API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Enrich security alerts with external attack surface context** — SOAR and SIEM vendors can pull Censys host profiles, threat labels, and service banners to automatically triage IP-based alerts, so analysts see hosting provider, exposed services, and reputation without leaving the platform. - **Sync externally-discovered assets into CAASM and ITAM tools** — Asset management platforms can continuously ingest internet-facing hosts, certificates, and web properties from Censys Collections to close shadow IT gaps and keep external inventory in sync with internal CMDBs. - **Power adversary infrastructure pivoting inside threat intel platforms** — TIPs can launch CensEye jobs on certificates, hosts, or web properties to expand a single IoC into the full set of related infrastructure, giving analysts a native pivot workflow instead of context-switching to Censys Search. - **Verify remediation and target state for vulnerability and pentest tools** — Vulnerability scanners and continuous pentest platforms can trigger on-demand rescans to confirm a service is patched or still exposed before running the next stage of their workflow. - **Track state changes on customer-owned external assets** — Monitoring and exposure management products can subscribe to Collection events to alert users when new ports open, certificates rotate, or services change on their monitored perimeter. ## What you can build - **IP and domain enrichment widget** — Render a side panel on any IP or hostname showing open ports, service banners, DNS records, Whois, and third-party threat tags via censys_hosts_enrichment and get_single_censys_host_by_id. - **Certificate-based infrastructure pivot** — Let users click a certificate fingerprint to spawn a CensEye job and return every host globally serving that certificate using create_a_censys_censeye_job and censys_censeye_jobs_list_results. - **On-demand rescan trigger** — Expose a 'Rescan now' action that calls censys_scans_rescan or create_a_censys_discovery_scan so users can validate live state instead of waiting for the next global scan cycle. - **Historical timeline for hosts** — Build a time-travel view of any IP using censys_hosts_event_history, censys_hosts_service_history, and censys_dns_ip_resolution_ranges to show how services and DNS records changed over time. - **Collections-driven change alerts** — Subscribe to censys_collections_list_events on customer-defined Collections to fire in-app notifications whenever an asset is added, a port opens, or a service changes. - **Credit usage and organization dashboards** — Surface Censys credit consumption and member activity inside your admin UI using censys_organizations_credits, censys_organizations_credits_usage, and censys_organizations_list_members. ## FAQs ### How do end users connect their Censys account? Truto handles Censys authentication for your users during the connect flow, so your app receives a ready-to-use connection without you managing API keys, org IDs, or credential rotation. ### Can we trigger live scans, or is data limited to Censys's scheduled crawls? Both are supported. You can query indexed data via the host, certificate, and web property endpoints, and force fresh probes on demand with censys_scans_rescan and create_a_censys_discovery_scan. ### How do we detect changes on a customer's attack surface without polling every host? Use Censys Collections. list_all_censys_collections identifies monitored asset groups and censys_collections_list_events streams add, remove, and state-change events you can turn into alerts. ### What historical data is available through the API? Censys exposes event history, service history, and DNS resolution ranges per host, letting you reconstruct what an IP was hosting or which names resolved to it at a prior point in time. ### How do we handle pagination and bulk lookups efficiently? Truto normalizes pagination across list_all_* endpoints, and Censys provides bulk_get variants for hosts, certificates, and web properties so you can hydrate many entities in a single call. ### Can we monitor Censys credit consumption for our customers? Yes. censys_organizations_credits, censys_organizations_credits_usage, censys_users_credits, and per-member usage endpoints let you display consumption and enforce quotas inside your product. ## Related reading - [Connect Censys to ChatGPT: Search and aggregate global asset data](https://truto.one/blog/connect-censys-to-chatgpt-search-and-aggregate-global-asset-data/) — Learn how to connect Censys to ChatGPT using Truto's managed MCP server. Search global assets, automate threat intelligence, and aggregate host data with AI. - [Connect Censys to Claude: Track host history and certificate records](https://truto.one/blog/connect-censys-to-claude-track-host-history-and-certificate-records/) — Learn how to connect Censys to Claude using a managed MCP server. This step-by-step guide covers how to track host history and certificates with AI agents. - [Connect Censys to AI Agents: Automate Discovery and Asset Management](https://truto.one/blog/connect-censys-to-ai-agents-automate-discovery-and-asset-management/) — Learn how to connect Censys to AI Agents using Truto's /tools endpoint. Build autonomous discovery, threat hunting, and asset management workflows without custom code.