Collections

Overview

Endpoints related to the Collections product

Available Operations

list - List collections
create - Create a collection
delete - Delete a collection
get - Get a collection
update - Update a collection
list_events - Get a collection's events
aggregate - Aggregate results for a search query within a collection
search - Run a search query within a collection

list

List all collections for an organization. Retrieved information includes collection ID, name, query, description, status, and asset count.

This endpoint does not cost credits to execute.

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.collections.list(page_token="<next_page_token>", page_size=1, collection_statuses=[
        censys_platform.CollectionStatuses.POPULATING,
        censys_platform.CollectionStatuses.ACTIVE,
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.
`page_token`	Optional[str]	➖	page token for the requested page of collection results
`page_size`	Optional[int]	➖	amount of results to return per page	1
`collection_statuses`	List[models.CollectionStatuses]	➖	statuses of collection for results to be filtered on.	[ "populating", "active" ]
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3CollectionsCrudListResponse

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	/

create

Create a new collection.

This endpoint does not cost 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.collections.create(crud_create_input_body={
        "description": "Hosts with services with AsyncRAT indicator in cert subject DN",
        "name": "Hosts services with AsyncRAT indicator",
        "query": "host.services.cert.parsed.subject_dn: \"asyncrat\"",
    })

    # Handle response
    print(res)

Parameters

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

Response

models.V3CollectionsCrudCreateResponse

Errors

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

delete

Delete a collection.

This endpoint does not cost 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.collections.delete(collection_uid="11111111-2222-3333-4444-555555555555")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`collection_uid`	str	✔️	The UID for the collection. Obtain the collection ID using the list collections endpoint or via the collection URL when using the web console.	11111111-2222-3333-4444-555555555555
`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.V3CollectionsCrudDeleteResponse

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

Retrieve information about a collection. Retrieved information includes its name, query, description, status, and asset count.

This endpoint does not cost 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.collections.get(collection_uid="11111111-2222-3333-4444-555555555555")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`collection_uid`	str	✔️	The UID for the collection. Obtain the collection ID using the list collections endpoint or via the collection URL when using the web console.	11111111-2222-3333-4444-555555555555
`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.V3CollectionsCrudGetResponse

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	/

update

Update a collection's name, description, and/or query.

This endpoint does not cost 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.collections.update(collection_uid="11111111-2222-3333-4444-555555555555", crud_update_input_body={
        "description": "Hosts with services with AsyncRAT indicator in cert subject DN",
        "name": "Hosts services with AsyncRAT indicator",
        "query": "host.services.cert.parsed.subject_dn: \"asyncrat\"",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`collection_uid`	str	✔️	The UID for the collection	11111111-2222-3333-4444-555555555555
`organization_id`	Optional[str]	➖	The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.
`crud_update_input_body`	Optional[models.CrudUpdateInputBody]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.V3CollectionsCrudUpdateResponse

Errors

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

list_events

Retrieve the event history for a collection. This includes the addition or removal of assets as well as collection status changes.

This endpoint does not cost credits to execute.

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.collections.list_events(request={
        "collection_uid": "11111111-2222-3333-4444-555555555555",
        "page_size": 1,
        "page_token": "<next_page_token>",
        "start_time": parse_datetime("2025-01-01T00:00:00Z"),
        "end_time": parse_datetime("2025-01-02T00:00:00Z"),
    })

    # Handle response
    print(res)

Parameters

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

Response

models.V3CollectionsListEventsResponse

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	/

aggregate

Aggregate results for a Platform search query that targets a collection's assets. 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.collections.aggregate(collection_uid="11111111-2222-3333-4444-555555555555", 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	Example
`collection_uid`	str	✔️	The UID for the collection. Obtain the collection ID using the list collections endpoint or via the collection URL when using the web console.	11111111-2222-3333-4444-555555555555
`search_aggregate_input_body`	models.SearchAggregateInputBody	✔️	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.V3CollectionsSearchAggregateResponse

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	/

search

Run a search query across a collection's assets. 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.collections.search(collection_uid="<id>", 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
`collection_uid`	str	✔️	The UID for the collection
`search_query_input_body`	models.SearchQueryInputBody	✔️	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.V3CollectionsSearchQueryResponse

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	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Collections

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

list_events

Example Usage

Parameters

Response

Errors

aggregate

Example Usage

Parameters

Response

Errors

search

Example Usage

Parameters

Response

Errors