Get Started with Data Downloads

The Censys Data Downloads API provides access to bulk Censys Platform data. This guide explains the structure of the data downloads and how to retrieve data files.

Structure

Data downloads have a three-tier hierarchical structure:

• Datasets
• Dataset snapshots
• Snapshot files

A dataset defines the type and scope of data available. Each dataset contains one or more snapshots. These snapshots are generally available on a daily basis. Snapshots are comprised of one or more files.

For example, the 2025-01-01 snapshot within the host-ipv4 dataset would contain a snapshot of all IPv4 host data for that day.

To obtain historical data for a particular date, you must retrieve the dataset snapshot for that date.

Datasets

Censys provides the following datasets. The datasets available to you will vary based on what your organization has access to.

File size

Approximate file sizes for the datasets are as follows.

Data schema

Data in the snapshots is structured following the Platform data schema.

The following tables provide more information about how data is structured for each asset type. The tables are not exhaustive but highlight in general how data is arranged for hosts, web properties, and certificates and focus on key fields for common use cases.

Host data schema

Detailed information about the host data schema is provided in the collapsible section below.

Web property data schema

Detailed information about the web property data schema is provided in the collapsible section below.

Certificate data schema

Detailed information about the certificate data schema is provided in the collapsible section below.

Format

Snapshots are available in AVRO and Parquet format.

The specific formats available may vary on a snapshot-by-snapshot basis.

Asynchronous downloads

Recent snapshots are generally ready to download without delay. However, when downloading older snapshots or the current day's snapshot, the files endpoint may return a 202 status with the message The files for this snapshot are currently being generated, and will be available soon. Please request them later.

For large datasets, it may take several hours before the data is ready to download. You can periodically retry the request until the files become available.

Data download API endpoints

API endpoints are available for the following operations.

GET https://data.censys.io/api/v1/datasets

GET https://data.censys.io/api/v1/datasets/{dataset}/snapshots

GET 
https://data.censys.io/api/v1/datasets/{dataset}/snapshots/{snapshot}/files/{format}

Example workflow

Prerequisites

• Your Censys organization ID. To find your organization ID:

  1. Go the the Censys Platform web console. Ensure that you have your Enterprise account selected.
  2. Your organization ID is provided in the URL after org=.
  

• Your Personal Access Token (PAT).

You must include your organization ID and PAT in all of your requests. Your organization ID is used to determine which datasets you have access to.

List and retrieve data

1. To list the datasets that you have access to, use the following:

   curl -H "Authorization: Bearer <your-api-token>" "https://data.censys.io/api/v1/datasets?org=<your-organization-id>"

   This will return a list of datasets, such as the example response provided below.

   {
     "datasets": [
       {
         "id": "host-ipv4",
         "description": "Daily IPv4 Host Snapshots"
       }
     ]
   }

2. List the available snapshots for a dataset using the following example. This will retrieve the snapshots available for the host-ipv4 dataset.

   curl -H "Authorization: Bearer <your-api-token>" "https://data.censys.io/api/v1/datasets/host-ipv4/snapshots?org=<your-organization-id>"

   You will receive a response similar to the one below.

   {
     "dataset": "host-ipv4",
     "snapshots": [
       {
         "id": "1234",
         "addedTime": "2025-01-01T00:00:00.00000000Z",
         "expireTime": "2025-11-31T00:00:00.00000000Z",
         "formats": [
           {
             "name": "AVRO"
           },
           {
             "name": "PARQUET"
           }
         ]
       }
     ]
   }

3. Use the id field from a snapshot to list the files that constitute a snapshot.

   curl -H "Authorization: Bearer <your-api-token>" "https://data.censys.io/api/v1/datasets/host-ipv4/snapshots/datasets/1234/?org=<your-organization-id>"

   You will a receive a response similar to the one below.

   {
     "dataset": "host-ipv4",
     "snapshot": "1234",
     "file": [
       {
         "url": "<signed url>",
         "sizeBytes": 10000
       }
     ]
   }

4. Use the signed URL to download the files or use a tool like DuckDB to query the files without downloading them.

   SELECT * FROM parquet_scan("<signed-url>") LIMIT 1;

BigQuery configuration

To ensure that your data exports function as expected when using BigQuery, enable the following boolean fields.