GlobalData

Overview

Endpoints related to the Global Data product

Available Operations

get_certificates - Retrieve multiple certificates
get_certificates_raw - Retrieve multiple certificates in PEM format
get_certificate - Get a certificate
get_certificate_raw - Get a certificate in PEM format
get_hosts - Retrieve multiple hosts
get_host - Get a host
list_services_on_host - Get service history for a host
get_host_timeline - Get host event history
get_web_properties - Retrieve multiple web properties
get_web_property - Get a web property
create_tracked_scan - Live Rescan: Initiate a new rescan
get_tracked_scan - Get scan status
aggregate - Aggregate results for a search query
convert_legacy_search_queries - Convert Legacy Search queries to Platform queries
search - Run a search query

get_certificates

Retrieve information about multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint in the Censys dataset.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_certificates(asset_certificate_list_input_body={
        "certificate_ids": [
            "3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`asset_certificate_list_input_body`	models.AssetCertificateListInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetCertificateListPostResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_certificates_raw

Retrieve the raw PEM-encoded format for multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint in the Censys dataset.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_certificates_raw(asset_certificate_list_input_body={
        "certificate_ids": [
            "3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`asset_certificate_list_input_body`	models.AssetCertificateListInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetCertificateListRawPostResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_certificate

Retrieve information about a single certificate. A certificate ID is its SHA-256 fingerprint in the Censys dataset.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_certificate(certificate_id="3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`certificate_id`	str	✔️	The SHA-256 certificate fingerprint.	3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetCertificateResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_certificate_raw

Retrieve the raw PEM-encoded format of a certificate. A certificate ID is its SHA-256 fingerprint in the Censys dataset.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_certificate_raw(certificate_id="3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`certificate_id`	str	✔️	The SHA-256 certificate fingerprint.	3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetCertificateRawResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_hosts

Retrieve information about multiple hosts. You can retrieve up to 100 hosts per call. A host ID is its IP address.

Example Usage

from censys_platform import SDK
from censys_platform.utils import parse_datetime


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_hosts(asset_host_list_input_body={
        "at_time": parse_datetime("2025-01-01T00:00:00Z"),
        "host_ids": [
            "8.8.8.8",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`asset_host_list_input_body`	models.AssetHostListInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetHostListPostResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_host

Retrieve information about a single host. A host ID is its IP address.

Example Usage

from censys_platform import SDK
from censys_platform.utils import parse_datetime


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_host(host_id="8.8.8.8", at_time=parse_datetime("2025-01-01T00:00:00Z"))

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`host_id`	str	✔️	The IP address of a host.	8.8.8.8
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`at_time`	date	➖	RFC3339 Timestamp to view a host at a specific point in time. Must be a valid RFC3339 string. Ensure that you suffix the date with T00:00:00Z or a specific time.	2025-01-01T00:00:00Z
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetHostResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

list_services_on_host

Retrieve historical service observations for a host. This endpoint returns time ranges during which services were detected on the host.

You can define a specific time frame of interest. If you do not specify a time frame, this endpoint will search the historical dataset that is available to your account.

You can filter by port number, protocol, and transport protocol.

Example Usage

import censys_platform
from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.list_services_on_host(request={
        "start_time": "2024-01-01T00:00:00Z",
        "end_time": "2024-01-31T23:59:59Z",
        "page_size": 50,
        "port": 443,
        "protocol": "HTTP",
        "transport_protocol": censys_platform.QueryParamTransportProtocol.TCP,
        "host_id": "8.8.8.8",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`request`	models.V3GlobaldataServiceOnHostRequest	✔️	The request object to use for the request.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataServiceOnHostResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404, 409	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_host_timeline

Retrieve event history for a host. A host ID is its IP address.

Note that when a service protocol changes after a new scan (for example, from UNKNOWN to NETBIOS), this information will be reflected in the scan object.

Example Usage

from censys_platform import SDK
from censys_platform.utils import parse_datetime


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_host_timeline(host_id="8.8.8.8", start_time=parse_datetime("2025-01-02T00:00:00Z"), end_time=parse_datetime("2025-01-01T00:00:00Z"))

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`host_id`	str	✔️	The IP address of a host.	8.8.8.8
`start_time`	date	✔️	Start time of the host timeline. Equivalent to the To field in the event history UI. This must be the timestamp closest to the current time. For example, if you want events from January 1, 2025 to the start of January 2, 2025, input the January 2 timestamp here. Must be a valid RFC3339 string. Ensure that you suffix the date with T00:00:00Z or a specific time.	2025-01-02T00:00:00Z
`end_time`	date	✔️	End time of the host timeline. Equivalent to the From field in the event history UI. This must be the timestamp furthest from the current time. For example, if you want events from January 1, 2025 to the start of January 2, 2025, input the January 1 timestamp here. Must be a valid RFC3339 string. Ensure that you suffix the date with T00:00:00Z or a specific time.	2025-01-01T00:00:00Z
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetHostTimelineResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_web_properties

Retrieve information about multiple web properties. You can retrieve up to 100 web properties per call. Web properties are identified using a combination of a hostname and port joined with a colon, such as platform.censys.io:80.

Example Usage

from censys_platform import SDK
from censys_platform.utils import parse_datetime


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_web_properties(asset_webproperty_list_input_body={
        "at_time": parse_datetime("2025-01-01T00:00:00Z"),
        "webproperty_ids": [
            "platform.censys.io:80",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`asset_webproperty_list_input_body`	models.AssetWebpropertyListInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetWebpropertyListPostResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_web_property

Retrieve information about a single web property. Web properties are identified using a combination of a hostname and port joined with a colon, such as platform.censys.io:80.

Example Usage

from censys_platform import SDK
from censys_platform.utils import parse_datetime


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_web_property(webproperty_id="platform.censys.io:80", at_time=parse_datetime("2025-01-01T00:00:00Z"))

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`webproperty_id`	str	✔️	A web property identifier.	platform.censys.io:80
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`at_time`	date	➖	RFC3339 Timestamp to view a webproperty at a specific point in time. Must be a valid RFC3339 string. Ensure that you suffix the date with T00:00:00Z or a specific time	2025-01-01T00:00:00Z
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataAssetWebpropertyResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404, 422	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

create_tracked_scan

Initiate a rescan for a known host service at a specific IP and port (ip:port) or hostname and port (hostname:port). This is equivalent to the Live Rescan feature available in the UI, but you can also target web properties in addition to hosts.

The scan may take several minutes to complete. The response will contain a scan ID that you can use to monitor the scan's status. After the scan completes, perform a lookup on the target asset to retrieve detailed scan information.

This endpoint is available to all Enterprise customers. It costs 10 credits to execute.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.create_tracked_scan(scans_rescan_input_body={
        "target": {
            "web_origin": {
                "hostname": "censys.io",
                "port": 443,
            },
        },
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`scans_rescan_input_body`	models.ScansRescanInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataScansRescanResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 422	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

get_tracked_scan

Retrieve the current status of a scan by its ID. This endpoint works for both Live Discovery scans and Live Rescans.

If the scan was successful, perform a lookup on the target asset to retrieve detailed scan information.

This endpoint is available to all Enterprise customers. This endpoint does not cost any credits to execute.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.get_tracked_scan(scan_id="5f39588f-d4c5-48e5-8894-0bb5918c28fa")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`scan_id`	str	✔️	The unique identifier of the tracked scan
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataScansGetResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 404	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

aggregate

Aggregate results for a Platform search query. This functionality is equivalent to the Report Builder in the Platform web UI.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.aggregate(search_aggregate_input_body={
        "field": "host.services.port",
        "number_of_buckets": 100,
        "query": "host.services.protocol=SSH",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`search_aggregate_input_body`	models.SearchAggregateInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataSearchAggregateResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 422	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

convert_legacy_search_queries

Convert Censys Search Language queries used in Legacy Search into Censys Query Language (CenQL) queries for use in the Platform.

Reference the documentation on CenQL for more information about query syntax.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.convert_legacy_search_queries(search_convert_query_input_body={
        "queries": [
            "<value 1>",
            "<value 2>",
            "<value 3>",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`search_convert_query_input_body`	models.SearchConvertQueryInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataSearchConvertResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

search

Run a search query across Censys data. Reference the documentation on Censys Query Language for information about query syntax. Host services that match your search criteria will be returned in a matched_services object.

Example Usage

from censys_platform import SDK


with SDK(
    organization_id="11111111-2222-3333-4444-555555555555",
    personal_access_token="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.global_data.search(search_query_input_body={
        "fields": [
            "host.ip",
        ],
        "page_size": 1,
        "query": "host.services: (protocol=SSH and not port: 22)",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`search_query_input_body`	models.SearchQueryInputBody	✔️	N/A
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. See the Getting Started docs for more information.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3GlobaldataSearchQueryResponse

Errors

Error Type	Status Code	Content Type
models.AuthenticationError	401	application/json
models.ErrorModel	400, 403, 422	application/problem+json
models.ErrorModel	500	application/problem+json
models.SDKError	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

GlobalData

Overview

Available Operations

get_certificates

Example Usage

Parameters

Response

Errors

get_certificates_raw

Example Usage

Parameters

Response

Errors

get_certificate

Example Usage

Parameters

Response

Errors

get_certificate_raw

Example Usage

Parameters

Response

Errors

get_hosts

Example Usage

Parameters

Response

Errors

get_host

Example Usage

Parameters

Response

Errors

list_services_on_host

Example Usage

Parameters

Response

Errors

get_host_timeline

Example Usage

Parameters

Response

Errors

get_web_properties

Example Usage

Parameters

Response

Errors

get_web_property

Example Usage

Parameters

Response

Errors

create_tracked_scan

Example Usage

Parameters

Response

Errors

get_tracked_scan

Example Usage

Parameters

Response

Errors

aggregate

Example Usage

Parameters

Response

Errors

convert_legacy_search_queries

Example Usage

Parameters

Response

Errors

search