Query API


The Query API allows executing SQL queries against our daily snapshots and raw data analogous to the Query web interface. Queries are executed asynchronously. You must first start a job, then check its status. Once a job has completed, you can view paginated results using the get results endpoint. Jobs typically require 15-30 seconds to execute; results can be viewed for 24 hours after the job completed. We also expose definition endpoints where you can list the series and view series details (i.e., list tables and schema).

Start Query Job


Description

The Start Query Job endpoint lets you to start a new asynchronous query job. Data should be posted as a JSON request document.

Endpoint
POST /api/v1/query
URL Parameters
(none)
Data Parameters
  • query [required string]
    The SQL query to be executed.

Example:

{
  "query":"SELECT location.country, count(ip) FROM ipv4.20151020 GROUP BY location.country;",
}
Success Response
200 SUCCESS
The job was submitted successfully.
Example:
{
  "status": "pending",
  "configuration": {
    "query": "select * from ipv4.20150902 limit 1000"
  },
  "job_id": "ahZzfnN0...OWUzZjY5DA"
}
Error Responses
  • 400 BAD REQUEST
    Your query could not be executed. See error for more information.
    Example:
    {"error_code":400, "error":"query could not be parsed"}
  • 429 RATE LIMIT EXCEEDED
    The requested record was not retrieved because you have exceeded your specified rate limit.
    Example:
    {"error_code":429, "error":"rate limit exceeded"}
  • 500 INTERNAL SERVER ERROR
    An unexpected error occurred when trying to execute your query. Try again at a later time or contact us at requests@censys.io if the problem persists.
    Example:
    {"error_code":500, "error":"unknown error occurred"}

Get Job Status


Description

The Get Job Status endpoint allows you to determine whether a job has completed. Once it has successfully finished, you can then retrieved results with the Get Results endpoint. Data should be posted as a JSON request document.

Endpoint
GET /api/v1/query/:job_id
URL Parameters
  • job_id [required string]
    The job ID received at job submission.

Example:

/api/v1/query/ahZzf...jY5DA
Data Parameters
(none)
Success Response
200 SUCCESS
The job was retrieved successfully.
Example:
{
  "status": "pending",
  "job_id": "ahZzfnN0ZW...zZjY5DA",
  "configuration": {
    "query": "select ip from ipv4.20150902 limit 1000"
  }
}
Error Responses
  • 404 NOT FOUND
    The specified job ID was invalid and could not be found.
    Example:
    {"error_code":404, "error":"page not found"}
  • 429 RATE LIMIT EXCEEDED
    The requested record was not retrieved because you have exceeded your specified rate limit.
    Example:
    {"error_code":429, "error":"rate limit exceeded"}
  • 500 INTERNAL SERVER ERROR
    An unexpected error occurred when trying to execute your query. Try again at a later time or contact us at requests@censys.io if the problem persists.
    Example:
    {"error_code":500, "error":"unknown error occurred"}

Get Job Results


Description

The Get Results endpoint allows you to retrieve results of a query after it has completed successfully.

Endpoint
GET /api/v1/query/:job_id/:page
URL Parameters
  • job_id [required string]
    The job ID received at job submission.

Example:

/api/v1/query/ahZzf...jY5DA
Data Parameters
(none)
Success Response
200 SUCCESS
The job was retreived successfully.
Example:
{
  "rows": [
    {
      "f": [
        {
          "v": "193.27.6.241"
        },
        {
          "v": null
        },
        {
          "v": null
        },
        {
          "v": "3239773937"
        }
      ]
    },
    {
      "f": [
        {
          "v": "193.27.6.242"
        },
        {
          "v": null
        },
        {
          "v": null
        },
        {
          "v": "3239773938"
        }
      ]
    }
  ],
  "statistics": {
    "rows": 5300,
    "pages": 6,
    "data_processed": 2072727909
  },
  "configuration": {
    "query": "select ip,updated_at, zdb_version, ipint from ipv4.20150902 limit 5300",
    "page": 2,
    "schema": {
      "fields": [
        {
          "type": "STRING",
          "name": "ip",
          "mode": "NULLABLE"
        },
        {
          "type": "TIMESTAMP",
          "name": "updated_at",
          "mode": "NULLABLE"
        },
        {
          "type": "INTEGER",
          "name": "zdb_version",
          "mode": "NULLABLE"
        },
        {
          "type": "INTEGER",
          "name": "ipint",
          "mode": "NULLABLE"
        }
      ]
    }
  }
}
Error Responses
  • 404 NOT FOUND
    The specified job ID was invalid and could not be found.
    Example:
    {"error_code":404, "error":"page not found"}
  • 429 RATE LIMIT EXCEEDED
    The requested record was not retrieved because you have exceeded your specified rate limit.
    Example:
    {"error_code":429, "error":"rate limit exceeded"}
  • 500 INTERNAL SERVER ERROR
    An unexpected error occurred when trying to execute your query. Try again at a later time or contact us at requests@censys.io if the problem persists.
    Example:
    {"error_code":500, "error":"unknown error occurred"}

Get Series


Description

The Get Series endpoint provides a list of series that can queried through the SQL interface. More information about each of the series can be retrieved with the Get Series Details endpoint.

Endpoint
GET /api/v1/query_definitions
URL Parameters
(none)
Data Parameters
(none)
Success Response
200 SUCCESS
List of series were successfully retrieved.
Example:
{
  "series": ["ipv4", "domain", "certificates", ...]
}

Get Series Details


Description

The Get Series Details endpoint provides details about a series, including the list of tables and schema for the series.

Endpoint
GET /api/v1/query_definitions/:series
URL Parameters
  • series [required string]
    The series's ID (as found from Get Series endpoint).

Example:

/api/v1/query_definitions/ipv4
Success Response
200 SUCCESS
Details about the series were successfully retrieved.
Example:
{
  "definition": {
    "fields": [
      {
        "type": "STRING",
        "name": "ip",
        "mode": "REQUIRED"
      },
      ...
      {
        "type": "TIMESTAMP",
        "name": "updated_at",
        "mode": "NULLABLE"
      }
  },
  "tables": [
    "ipv4.20150722",
    ...
    "ipv4.20151020"
  ]
}
Error Responses
  • 404 NOT FOUND
    The specified series does not exist.
    Example:
    {"error_code":404, "error":""}