# Censys

> Look up and search Censys' internet-wide scan data on hosts, certificates and websites, read their history, manage collections, hunt threats and manage your attack surface's seeds and risks, with triggers for new search results, collection changes and new risks.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/censys

## Actions

### Add attack surface seeds

Add up to 50 seeds to your attack surface: IP addresses, CIDR blocks, ASNs (such as AS15169), domains or certificate fingerprints. Adding one already there is not an error. Free.

**Inputs**

- Seeds (`seeds`, list, required): The seeds to add, such as example.com, 203.0.113.0/24 or AS15169.

**Outputs**

- `count` (number): How many
- `seeds` (list): The seeds added

**Example output**

```json
{
  "count": 1,
  "seeds": [
    {
      "asset": "example.com",
      "type": "domain"
    }
  ]
}
```

### Convert Legacy Search queries

Rewrite queries written for Censys Legacy Search in the Platform's CenQL, with notes on anything that didn't carry over.

**Inputs**

- Legacy queries (`legacy_queries`, list, required): One or more Legacy Search queries, up to 50.

**Outputs**

- `conversions` (list): Each query with its CenQL version
- `count` (number): How many queries

**Example output**

```json
{
  "conversions": [
    {
      "comments": [],
      "converted_query": "host.services.protocol: SSH",
      "errors": [],
      "original_query": "services.service_name: SSH",
      "targets": [
        "host"
      ]
    }
  ],
  "count": 1
}
```

### Count collection by field

Count a collection's assets matching a CenQL query by one field's values, such as port, country or software.

**Inputs**

- Collection (`collection_id`, text, required): The collection. Pick one, or give its ID from an earlier step.
- Query (`query`, text, required): A Censys Query Language (CenQL) query, as typed in the Censys search bar.
- Break down by (`aggregate_field`, text, required): The field whose values to count, in dot notation, such as host.services.port or host.location.country.
- Number of values (`number_of_buckets`, number): How many of the most common values to return, 1 to 2,000. Defaults to 25. From 1 to 2000.
- Only values the query matches (`filter_by_query`, true/false): Count only values that match the query itself. Off counts every value on the matching records, such as every port on a host found for SSH.
- Count by (`count_by_level`, text): For a nested field, what each count counts: leave empty for the deepest level, '.' for whole records (such as hosts), or a level such as host.services.

**Outputs**

- `buckets` (list): Each value with how many have it
- `count` (number): How many values
- `is_more_than_total_hits` (true/false): True when the counts are estimates
- `other_count` (number): How many have a value not listed
- `query_duration_millis` (number): How long it took, in milliseconds
- `total_count` (number): How many records matched

**Example output**

```json
{
  "buckets": [
    {
      "count": 40,
      "key": "3389"
    },
    {
      "count": 12,
      "key": "443"
    }
  ],
  "count": 2,
  "is_more_than_total_hits": false,
  "other_count": 0,
  "query_duration_millis": 31,
  "total_count": 42
}
```

### Count search results by field

Count a CenQL query's matches by one field's values, such as port, country or ASN, without fetching every record, like Censys' Report Builder.

**Inputs**

- Query (`query`, text, required): A Censys Query Language (CenQL) query, as typed in the Censys search bar.
- Break down by (`aggregate_field`, text, required): The field whose values to count, in dot notation, such as host.services.port or host.location.country.
- Number of values (`number_of_buckets`, number): How many of the most common values to return, 1 to 2,000. Defaults to 25. From 1 to 2000.
- Only values the query matches (`filter_by_query`, true/false): Count only values that match the query itself. Off counts every value on the matching records, such as every port on a host found for SSH.
- Count by (`count_by_level`, text): For a nested field, what each count counts: leave empty for the deepest level, '.' for whole records (such as hosts), or a level such as host.services.

**Outputs**

- `buckets` (list): Each value with how many have it
- `count` (number): How many values
- `is_more_than_total_hits` (true/false): True when the counts are estimates
- `other_count` (number): How many have a value not listed
- `query_duration_millis` (number): How long it took, in milliseconds
- `total_count` (number): How many records matched

**Example output**

```json
{
  "buckets": [
    {
      "count": 120034,
      "key": "22"
    },
    {
      "count": 8123,
      "key": "2222"
    }
  ],
  "count": 2,
  "is_more_than_total_hits": false,
  "other_count": 0,
  "query_duration_millis": 340,
  "total_count": 128157
}
```

### Create collection

Save a CenQL query as a collection: a group of assets Censys keeps up to date as the internet changes, which the collection triggers can watch. Free.

**Inputs**

- Name (`name`, text, required): The collection's name.
- Query (`query`, text, required): A Censys Query Language (CenQL) query, as typed in the Censys search bar.
- Description (`description`, text): What the collection is for.
- Who can see it (`privacy`, text): Private to you, or shared with your organization. One of: `private` (Private: only you (default)), `shared` (Shared with your organization).

**Outputs**

- `collection` (object): The collection

**Example output**

```json
{
  "collection": {
    "added_assets_24_hours": 3,
    "create_time": "2026-10-01T09:00:00Z",
    "created_by": "6f2a9a8e-1c1d-4f6b-9a2e-3c4d5e6f7a8b",
    "description": "Hosts with RDP open in our ranges",
    "id": "364133a0-53ae-4f51-82d0-17c25aed92e3",
    "name": "Internet-facing RDP",
    "privacy": "private",
    "query": "host.services.protocol=\"RDP\" and host.autonomous_system.asn=20115",
    "removed_assets_24_hours": 1,
    "status": "populating",
    "status_reason": "initial",
    "total_assets": 42
  }
}
```

### Delete collection

Delete a collection. Free.

**Inputs**

- Collection (`collection_id`, text, required): The collection. Pick one, or give its ID from an earlier step.

**Outputs**

- `collection_id` (text): The collection deleted
- `deleted` (true/false): Always true once deleted

**Example output**

```json
{
  "collection_id": "364133a0-53ae-4f51-82d0-17c25aed92e3",
  "deleted": true
}
```

### Get certificate

Look up a TLS certificate by its SHA-256 fingerprint: who it was issued to and by, the names it covers, when it is valid and whether it was revoked. Costs one Censys credit.

**Inputs**

- Certificate SHA-256 fingerprint (`certificate_fingerprint`, text, required): The certificate's SHA-256 fingerprint: 64 hexadecimal characters, colons allowed.

**Outputs**

- `certificate` (object): The certificate

**Example output**

```json
{
  "certificate": {
    "added_at": "2026-09-01T02:11:09Z",
    "fingerprint_sha1": "8d4c0a8f9b3c1e1d2a6b5c4d3e2f1a0b9c8d7e6f",
    "fingerprint_sha256": "f9f055ac237c123b9a7a8644832319ad41d399c9f714f52bc6a02c4a875cfb27",
    "names": [
      "www.example.com",
      "example.com"
    ],
    "parsed": {
      "issuer_dn": "C=US, O=Let's Encrypt, CN=R11",
      "serial_number": "421389561781245312341234",
      "subject_dn": "CN=www.example.com",
      "validity_period": {
        "not_after": "2026-11-30T00:00:00Z",
        "not_before": "2026-09-01T00:00:00Z"
      }
    },
    "revoked": false,
    "validation_level": "dv"
  }
}
```

### Get collection

Get one collection with its query, status and how many assets it holds and gained or lost in the last day. Free.

**Inputs**

- Collection (`collection_id`, text, required): The collection. Pick one, or give its ID from an earlier step.

**Outputs**

- `collection` (object): The collection

**Example output**

```json
{
  "collection": {
    "added_assets_24_hours": 3,
    "create_time": "2026-10-01T09:00:00Z",
    "created_by": "6f2a9a8e-1c1d-4f6b-9a2e-3c4d5e6f7a8b",
    "description": "Hosts with RDP open in our ranges",
    "id": "364133a0-53ae-4f51-82d0-17c25aed92e3",
    "name": "Internet-facing RDP",
    "privacy": "private",
    "query": "host.services.protocol=\"RDP\" and host.autonomous_system.asn=20115",
    "removed_assets_24_hours": 1,
    "status": "active",
    "status_reason": "initial",
    "total_assets": 42
  }
}
```

### Get credit balance

Get your organization's Censys credit balance, when its credits expire, and its automatic top up setting. Free.

**Inputs**: None.

**Outputs**

- `auto_replenish` (object): Whether credits top up by themselves
- `balance` (number): Credits left
- `credit_expirations` (list): Each batch of credits with when it expires
- `organization_id` (text): The organization

**Example output**

```json
{
  "auto_replenish": {
    "amount": 0,
    "enabled": false,
    "threshold": 0
  },
  "balance": 48210,
  "credit_expirations": [
    {
      "balance": 48210,
      "created_at": "2026-01-15T00:00:00Z",
      "expires_at": "2027-01-15T00:00:00Z",
      "initial_balance": 50000
    }
  ],
  "organization_id": "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
}
```

### Get DNS history

See the DNS records a domain resolved to (A, AAAA, MX, NS, SOA, TXT), with when each was first and last seen. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Domain (`domain`, text, required): The domain or host name, such as example.com.
- Record types (`record_types`, list): Only these kinds of record. Leave empty for all. One or more of: `A` (A (IPv4 address)), `AAAA` (AAAA (IPv6 address)), `MX` (MX (mail server)), `NS` (NS (name server)), `SOA` (SOA (zone authority)), `TXT` (TXT (text)).
- From (`from_time`, date and time): Start of the window. Leave empty for as far back as your plan allows.
- Until (`until_time`, date and time): End of the window. Leave empty for now.
- Page size (`page_size`, number): How many to return, 1 to 100. Censys' default is 100. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `name` (text): The name looked up
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `records` (list): The records and when seen
- `total_records` (number): How many records in all

**Example output**

```json
{
  "count": 1,
  "name": "example.com",
  "next_page_token": "",
  "records": [
    {
      "first_observed": "2026-10-01T00:00:00Z",
      "last_observed": "2026-11-06T00:00:00Z",
      "record_type": "A",
      "value": "93.184.215.14"
    }
  ],
  "total_records": 1
}
```

### Get host

Look up an IP address: its open services and software, location, network owner, DNS names and labels, now or at a past time. Costs one Censys credit.

**Inputs**

- IP address (`host_ip`, text, required): The host's IP address, IPv4 or IPv6.
- As it was at (`at_time`, date and time): See the record as Censys saw it at this time. Leave empty for now.

**Outputs**

- `host` (object): The host

**Example output**

```json
{
  "host": {
    "autonomous_system": {
      "asn": 20115,
      "bgp_prefix": "47.33.192.0/19",
      "country_code": "US",
      "description": "ACME-20115",
      "name": "ACME-20115"
    },
    "dns": {
      "names": [
        "syn-047-033-210-014.res.acme.com"
      ],
      "reverse_dns": {
        "names": [
          "syn-047-033-210-014.res.acme.com"
        ]
      }
    },
    "ip": "47.33.210.14",
    "labels": [],
    "location": {
      "city": "Mount Pleasant",
      "continent": "North America",
      "coordinates": {
        "latitude": 43.59781,
        "longitude": -84.76751
      },
      "country": "United States",
      "country_code": "US",
      "postal_code": "48858",
      "province": "Michigan",
      "timezone": "America/Detroit"
    },
    "service_count": 1,
    "services": [
      {
        "banner_hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "port": 7547,
        "protocol": "CWMP",
        "scan_time": "2026-11-06T19:03:55Z",
        "transport_protocol": "tcp"
      }
    ],
    "whois": {
      "network": {
        "handle": "AC04",
        "name": "Acme"
      }
    }
  }
}
```

### Get host history

See what changed on an IP address between two times: services opened or closed, certificates swapped, software changed. How far back you can look depends on your plan.

**Inputs**

- IP address (`host_ip`, text, required): The host's IP address, IPv4 or IPv6.
- From (`from_time`, date and time, required): Start of the window.
- Until (`until_time`, date and time): End of the window. Leave empty for now.

**Outputs**

- `count` (number): How many changes
- `events` (list): Each change Censys saw, newest first
- `scanned_to` (text): Censys has scanned the host up to this time

**Example output**

```json
{
  "count": 1,
  "events": [
    {
      "extensions": {},
      "resource": {
        "event_time": "2026-11-05T10:12:00Z",
        "service_scanned": {
          "scan": {
            "port": 443,
            "protocol": "HTTP"
          }
        }
      }
    }
  ],
  "scanned_to": "2026-11-06T19:03:55Z"
}
```

### Get host threat history

See when threats were detected on an IP address, as time ranges, to tell whether it was malicious during an incident. Needs the Adversary Investigation module.

**Inputs**

- IP address (`host_ip`, text, required): The host's IP address, IPv4 or IPv6.
- From (`from_time`, date and time): Start of the window. Leave empty for as far back as your plan allows.
- Until (`until_time`, date and time): End of the window. Leave empty for now.
- Threat (`threat_name`, text): Only this threat, by name. Leave empty for all.
- Port (`port`, number): Only this port. Leave empty for all. From 1 to 65535.
- Transport (`transport_protocol`, text): Only TCP or only UDP. Leave empty for both. One of: `tcp`, `udp`.
- Page size (`page_size`, number): How many to return, 1 to 100. Censys' default is 100. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `ranges` (list): Each threat with when it was seen

**Example output**

```json
{
  "count": 1,
  "next_page_token": "",
  "ranges": [
    {
      "end_time": "2026-11-02T00:00:00Z",
      "ip": "47.33.210.14",
      "port": "443",
      "protocol": "HTTP",
      "start_time": "2026-10-28T00:00:00Z",
      "threat_name": "Cobalt Strike",
      "transport_protocol": "tcp"
    }
  ]
}
```

### Get hosts seen with certificate

See every IP address that presented a certificate, and when, to find other infrastructure using it. Needs the Adversary Investigation module.

**Inputs**

- Certificate SHA-256 fingerprint (`certificate_fingerprint`, text, required): The certificate's SHA-256 fingerprint: 64 hexadecimal characters, colons allowed.
- From (`from_time`, date and time): Start of the window. Leave empty for as far back as your plan allows.
- Until (`until_time`, date and time): End of the window. Leave empty for now.
- Port (`port`, number): Only this port. Leave empty for all. From 1 to 65535.
- Page size (`page_size`, number): How many to return, 1 to 100. Censys' default is 100. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `ranges` (list): Each host with when it presented the certificate
- `total_results` (number): How many in all

**Example output**

```json
{
  "count": 1,
  "next_page_token": "",
  "ranges": [
    {
      "end_time": "2026-11-06T00:00:00Z",
      "ip": "47.33.210.14",
      "port": 443,
      "protocols": [
        "HTTP"
      ],
      "start_time": "2026-10-01T00:00:00Z",
      "transport_protocol": "tcp"
    }
  ],
  "total_results": 1
}
```

### Get web property

Look up a website by host name and port: its pages, software, certificate, threats and vulnerabilities, now or at a past time. Costs one Censys credit.

**Inputs**

- Host name (`hostname`, text, required): The website's host name, such as www.example.com.
- Port (`port`, number): The port it answers on. Defaults to 443. From 1 to 65535.
- As it was at (`at_time`, date and time): See the record as Censys saw it at this time. Leave empty for now.

**Outputs**

- `web_property` (object): The web property
- `web_property_id` (text): Censys' ID for it, hostname:port

**Example output**

```json
{
  "web_property": {
    "cert": {
      "fingerprint_sha256": "f9f055ac237c123b9a7a8644832319ad41d399c9f714f52bc6a02c4a875cfb27",
      "names": [
        "www.example.com",
        "example.com"
      ]
    },
    "endpoints": [
      {
        "endpoint_type": "HTTP",
        "path": "/"
      }
    ],
    "hostname": "www.example.com",
    "port": 443,
    "scan_time": "2026-11-06T19:03:55Z",
    "software": [
      {
        "product": "nginx",
        "vendor": "nginx"
      }
    ],
    "threats": [],
    "vulns": []
  },
  "web_property_id": "www.example.com:443"
}
```

### List active threats

List the threats (malware, C2 frameworks and other malicious infrastructure) Censys currently sees, with how many hosts and websites show each. Needs the Adversary Investigation module.

**Inputs**

- Filter (`query`, text): A CenQL filter to narrow the list. Leave empty for every threat.

**Outputs**

- `count` (number): How many threats
- `threats` (list): The threats

**Example output**

```json
{
  "count": 1,
  "threats": [
    {
      "added_at": "2025-01-10T00:00:00Z",
      "count": 812,
      "description": "A commercial adversary simulation framework.",
      "host_count": 790,
      "id": "cobalt-strike",
      "name": "Cobalt Strike",
      "references": [
        "https://www.cobaltstrike.com/"
      ],
      "web_count": 22
    }
  ]
}
```

### List attack surface seeds

List the seeds (IPs, CIDR blocks, ASNs, domains and certificates) Censys discovers your attack surface from. Needs Attack Surface Management. Free.

**Inputs**

- Page size (`page_size`, number): How many to return, 1 to 200. Censys' default is 50. From 1 to 200.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `seeds` (list): The seeds

**Example output**

```json
{
  "count": 2,
  "next_page_token": "",
  "seeds": [
    {
      "asset": "example.com",
      "type": "domain"
    },
    {
      "asset": "203.0.113.0/24",
      "type": "netblock"
    }
  ]
}
```

### List collection events

List what happened to a collection: assets added or removed, and status changes, with when and why. Free. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Collection (`collection_id`, text, required): The collection. Pick one, or give its ID from an earlier step.
- Kind of event (`event_kind`, text): Only asset changes, or only status changes. Leave empty for both. One of: `asset` (Assets added or removed), `status` (Status changes).
- Asset change (`asset_change`, text): Only assets added, or only assets removed. Leave empty for both. One of: `added`, `removed`.
- From (`from_time`, date and time): Start of the window. Leave empty for as far back as your plan allows.
- Until (`until_time`, date and time): End of the window. Leave empty for now.
- Page size (`page_size`, number): How many to return, 1 to 100. Leave empty for Censys' default. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `events` (list): Each event: an asset_change or a status_change
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one

**Example output**

```json
{
  "count": 1,
  "events": [
    {
      "asset_change": {
        "change_type": "added",
        "event_time": "2026-11-06T20:03:01Z",
        "reason": "host 47.33.210.14 was added to collection 364133a0-53ae-4f51-82d0-17c25aed92e3 based on the collection query."
      },
      "status_change": {}
    }
  ],
  "next_page_token": ""
}
```

### List collections

List your organization's collections with their queries, status and asset counts. Free. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Status (`statuses`, list): Only collections in these states. Leave empty for all. One or more of: `populating`, `active`, `paused`, `archived`.
- Page size (`page_size`, number): How many to return, 1 to 100. Leave empty for Censys' default. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `collections` (list): The collections
- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one

**Example output**

```json
{
  "collections": [
    {
      "added_assets_24_hours": 3,
      "create_time": "2026-10-01T09:00:00Z",
      "created_by": "6f2a9a8e-1c1d-4f6b-9a2e-3c4d5e6f7a8b",
      "description": "Hosts with RDP open in our ranges",
      "id": "364133a0-53ae-4f51-82d0-17c25aed92e3",
      "name": "Internet-facing RDP",
      "privacy": "private",
      "query": "host.services.protocol=\"RDP\" and host.autonomous_system.asn=20115",
      "removed_assets_24_hours": 1,
      "status": "active",
      "status_reason": "initial",
      "total_assets": 42
    }
  ],
  "count": 1,
  "next_page_token": ""
}
```

### List risk events

List risks opened, resolved or reopened on your attack surface, with the risk, its severity and the affected asset. Needs Attack Surface Management. Free. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Change (`change_types`, list): Only these changes. Leave empty for all. One or more of: `opened`, `resolved`, `reopened`.
- Severity (`severities`, list): Only risks of these severities. Leave empty for all. One or more of: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`.
- Rapid response (`rapid_response`, text): Only risks Censys flagged for rapid response, or only the rest. Leave empty for both. One of: `true` (Only rapid response risks), `false` (Only other risks).
- Happened from (`from_time`, date and time): Start of a time range. Give Happened until with it.
- Happened until (`until_time`, date and time): End of the time range. Give Happened from with it.
- Recorded after (`inserted_after`, date and time): Only events Censys recorded after this time, oldest first. Use instead of a time range.
- Page size (`page_size`, number): How many to return, 1 to 1000. Censys' default is 100. From 1 to 1000.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `risk_events` (list): The risk events

**Example output**

```json
{
  "count": 1,
  "next_page_token": "",
  "risk_events": [
    {
      "change_type": "opened",
      "id": "9472333883494777",
      "inserted_at": "2026-11-06T20:40:00Z",
      "occurred_at": "2026-11-06T20:39:09Z",
      "risk_instance": {
        "asset_type": "host",
        "description": "An end-of-life version of OpenSSL is in use.",
        "host": {
          "ip": "47.33.210.14"
        },
        "id": "ri_550",
        "rapid_response": false,
        "risk_category": "Vulnerability",
        "risk_name": "EOL OpenSSL Software",
        "risk_type_id": "eol-openssl-software",
        "severity": "MEDIUM",
        "status": "open",
        "web": {
          "hostname": "www.example.com",
          "port": 443
        }
      }
    }
  ]
}
```

### Remove attack surface seed

Remove a seed from your attack surface. Removing one that isn't there is not an error. Free.

**Inputs**

- Seed (`seed`, text, required): The seed, exactly as it was added. Pick one, or type it.

**Outputs**

- `removed` (true/false): Always true once removed
- `seed` (text): The seed removed

**Example output**

```json
{
  "removed": true,
  "seed": "example.com"
}
```

### Search

Search Censys' internet-wide data for hosts, certificates and web properties with a CenQL query, such as a banner, JARM, favicon hash or software. Gets one page of up to 100; each page costs a credit.

**Inputs**

- Query (`query`, text, required): A Censys Query Language (CenQL) query, as typed in the Censys search bar.
- Only these fields (`fields`, list): Return only these fields of each result, in dot notation, such as host.ip. Leave empty for every field.
- Page size (`page_size`, number): How many to return, 1 to 100. Censys' default is 100. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `hits` (list): The matching assets; each names its asset_type and asset_id
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `previous_page_token` (text): The token for the page before this one
- `query_duration_millis` (number): How long the search took, in milliseconds
- `total_hits` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "hits": [
    {
      "asset_id": "47.33.210.14",
      "asset_type": "host",
      "certificate_v1": {},
      "host_v1": {
        "matched_services": [
          {
            "port": 7547,
            "protocol": "CWMP"
          }
        ],
        "resource": {
          "autonomous_system": {
            "asn": 20115,
            "bgp_prefix": "47.33.192.0/19",
            "country_code": "US",
            "description": "ACME-20115",
            "name": "ACME-20115"
          },
          "dns": {
            "names": [
              "syn-047-033-210-014.res.acme.com"
            ],
            "reverse_dns": {
              "names": [
                "syn-047-033-210-014.res.acme.com"
              ]
            }
          },
          "ip": "47.33.210.14",
          "labels": [],
          "location": {
            "city": "Mount Pleasant",
            "continent": "North America",
            "coordinates": {
              "latitude": 43.59781,
              "longitude": -84.76751
            },
            "country": "United States",
            "country_code": "US",
            "postal_code": "48858",
            "province": "Michigan",
            "timezone": "America/Detroit"
          },
          "service_count": 1,
          "services": [
            {
              "banner_hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
              "port": 7547,
              "protocol": "CWMP",
              "scan_time": "2026-11-06T19:03:55Z",
              "transport_protocol": "tcp"
            }
          ],
          "whois": {
            "network": {
              "handle": "AC04",
              "name": "Acme"
            }
          }
        }
      },
      "tags": [],
      "webproperty_v1": {}
    }
  ],
  "next_page_token": "",
  "previous_page_token": "",
  "query_duration_millis": 112,
  "total_hits": 1
}
```

### Search attack surface

Search only your attack surface's hosts, web properties and certificates with a CenQL query; a query on risk fields returns risks instead. Needs Attack Surface Management. Gets one page of up to 100.

**Inputs**

- Query (`query`, text, required): A Censys Query Language (CenQL) query, as typed in the Censys search bar.
- Only these fields (`fields`, list): Return only these fields of each result, in dot notation, such as host.ip. Leave empty for every field.
- Page size (`page_size`, number): How many to return, 1 to 100. Censys' default is 100. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `hits` (list): The matching assets; each names its asset_type and asset_id
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `previous_page_token` (text): The token for the page before this one
- `query_duration_millis` (number): How long the search took, in milliseconds
- `total_hits` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "hits": [
    {
      "asset_id": "47.33.210.14",
      "asset_type": "host",
      "certificate_v1": {},
      "host_v1": {
        "matched_services": [
          {
            "port": 7547,
            "protocol": "CWMP"
          }
        ],
        "resource": {
          "autonomous_system": {
            "asn": 20115,
            "bgp_prefix": "47.33.192.0/19",
            "country_code": "US",
            "description": "ACME-20115",
            "name": "ACME-20115"
          },
          "dns": {
            "names": [
              "syn-047-033-210-014.res.acme.com"
            ],
            "reverse_dns": {
              "names": [
                "syn-047-033-210-014.res.acme.com"
              ]
            }
          },
          "ip": "47.33.210.14",
          "labels": [],
          "location": {
            "city": "Mount Pleasant",
            "continent": "North America",
            "coordinates": {
              "latitude": 43.59781,
              "longitude": -84.76751
            },
            "country": "United States",
            "country_code": "US",
            "postal_code": "48858",
            "province": "Michigan",
            "timezone": "America/Detroit"
          },
          "service_count": 1,
          "services": [
            {
              "banner_hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
              "port": 7547,
              "protocol": "CWMP",
              "scan_time": "2026-11-06T19:03:55Z",
              "transport_protocol": "tcp"
            }
          ],
          "whois": {
            "network": {
              "handle": "AC04",
              "name": "Acme"
            }
          }
        }
      },
      "tags": [],
      "webproperty_v1": {}
    }
  ],
  "next_page_token": "",
  "previous_page_token": "",
  "query_duration_millis": 41,
  "total_hits": 1
}
```

### Search collection

Search only a collection's assets with a CenQL query, so results stay inside the scope you monitor. Gets one page of up to 100.

**Inputs**

- Collection (`collection_id`, text, required): The collection. Pick one, or give its ID from an earlier step.
- Query (`query`, text, required): A Censys Query Language (CenQL) query, as typed in the Censys search bar.
- Only these fields (`fields`, list): Return only these fields of each result, in dot notation, such as host.ip. Leave empty for every field.
- Page size (`page_size`, number): How many to return, 1 to 100. Censys' default is 100. From 1 to 100.
- Page token (`page_token`, text): The 'next_page_token' from an earlier run, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `hits` (list): The matching assets; each names its asset_type and asset_id
- `next_page_token` (text): Pass as 'Page token' for the next page; empty on the last one
- `previous_page_token` (text): The token for the page before this one
- `query_duration_millis` (number): How long the search took, in milliseconds
- `total_hits` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "hits": [
    {
      "asset_id": "47.33.210.14",
      "asset_type": "host",
      "certificate_v1": {},
      "host_v1": {
        "matched_services": [
          {
            "port": 7547,
            "protocol": "CWMP"
          }
        ],
        "resource": {
          "autonomous_system": {
            "asn": 20115,
            "bgp_prefix": "47.33.192.0/19",
            "country_code": "US",
            "description": "ACME-20115",
            "name": "ACME-20115"
          },
          "dns": {
            "names": [
              "syn-047-033-210-014.res.acme.com"
            ],
            "reverse_dns": {
              "names": [
                "syn-047-033-210-014.res.acme.com"
              ]
            }
          },
          "ip": "47.33.210.14",
          "labels": [],
          "location": {
            "city": "Mount Pleasant",
            "continent": "North America",
            "coordinates": {
              "latitude": 43.59781,
              "longitude": -84.76751
            },
            "country": "United States",
            "country_code": "US",
            "postal_code": "48858",
            "province": "Michigan",
            "timezone": "America/Detroit"
          },
          "service_count": 1,
          "services": [
            {
              "banner_hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
              "port": 7547,
              "protocol": "CWMP",
              "scan_time": "2026-11-06T19:03:55Z",
              "transport_protocol": "tcp"
            }
          ],
          "whois": {
            "network": {
              "handle": "AC04",
              "name": "Acme"
            }
          }
        }
      },
      "tags": [],
      "webproperty_v1": {}
    }
  ],
  "next_page_token": "",
  "previous_page_token": "",
  "query_duration_millis": 54,
  "total_hits": 1
}
```

### Update collection

Change a collection's name, query, description or who can see it. Only the fields given change. Free.

**Inputs**

- Collection (`collection_id`, text, required): The collection. Pick one, or give its ID from an earlier step.
- Name (`name`, text): A new name. Leave empty to keep it.
- Query (`query`, text): A new CenQL query. Leave empty to keep it.
- Description (`description`, text): A new description. Leave empty to keep it.
- Who can see it (`privacy`, text): Private to you, or shared with your organization. One of: `private` (Private: only you (default)), `shared` (Shared with your organization).

**Outputs**

- `collection` (object): The collection

**Example output**

```json
{
  "collection": {
    "added_assets_24_hours": 3,
    "create_time": "2026-10-01T09:00:00Z",
    "created_by": "6f2a9a8e-1c1d-4f6b-9a2e-3c4d5e6f7a8b",
    "description": "Hosts with RDP open in our ranges",
    "id": "364133a0-53ae-4f51-82d0-17c25aed92e3",
    "name": "RDP on our network",
    "privacy": "private",
    "query": "host.services.protocol=\"RDP\" and host.autonomous_system.asn=20115",
    "removed_assets_24_hours": 1,
    "status": "active",
    "status_reason": "initial",
    "total_assets": 42
  }
}
```
