Export API


The Export API allows exporting large datasets and structured records from Censys to JSON or CSV files. Unlike the query endpoint, there are no limits on the type or amount of data returned.

Exports are executed as asynchronous jobs. You must first start a job. If the query is parsed successfully, the call will return a job ID, which is used in subsequent calls to get job. Once a job executes successfully, the get job endpoint will provide a list of 128MB JSON files that are available for download for 24 hours. Jobs typically require 15-30 seconds to execute.

Start Export Job


Description

The Start Export Job endpoint lets you submit an export job. Data should be posted as a JSON request document.

Endpoint
POST /api/v1/export
URL Parameters
(none)
Data Parameters
  • query [required string]
    The SQL query to be executed.
  • format [optional string]
    The format data should be output in. Must be csv or json. Default: csv.
  • flatten [optional boolean]
    Should nested and repeated fields in the query results be flattened. Default: true.
  • compress [optional boolean]
    Should data files be gzipped. Default: false.
  • delimeter [optional string] (CSV only)
    Delimiter to use between fields in the exported data. Default: ",".
  • headers [optional boolean] (CSV only)
    Should a header row be included in results files. Default: true.

Example:

{
  "query":"SELECT location.country, count(ip) FROM ipv4.20151020 GROUP BY location.country;",
  "format":"json",
  "flatten":false
}
Success Response
200 SUCCESS
The job was submitted successfully.
Example:
{
  "status": "pending",
  "configuration": {
    "format": "json",
    "compress": false,
    "headers": false,
    "delimiter": null,
    "flatten": false,
    "query": "select * from ipv4.20150902 limit 1000"
  },
  "job_id": "ahZzfnN0ZWFkeS1jaXJjdWl0LTkxNDE3cjsLEhFCaWdRdWVyeUV4ZWN1dGlvbiIkMjk0MzA1NzgtNzkzOC0xMWU1LTlmMTQtZjUwN2FhOWUzZjY5DA"
}
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 lets you retrieved information about a previously submitted job. The status field will return "pending" until the job has completed at which time status will be "success" or "error". On success, the output will define download_paths, a list of files that can be downloaded for the next 24 hours. After 24 hour, the job status will change to "expired" and the files will no longer be retrievable.

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

Example:

/api/v1/export/ahZzf...jY5DA
Data Parameters
(none)
Success Response
200 SUCCESS
The job was retreived successfully.
Example:
{
  "status": "success",
  "statistics": {
    "backend_time": null,
    "result_count": null
  },
  "job_id": "ahZzfnN0ZWFkeS1jaXJjdWl0LTkxNDE3cjsLEhFCaWdRdWVyeUV4ZWN1dGlvbiIkZTdjNDFhM2EtNzkzOC0xMWU1LTlhMWMtZjUwN2FhOWUzZjY5DA",
  "configuration": {
    "format": "json",
    "compress": false,
    "headers": false,
    "delimiter": false,
    "flatten": false,
    "query": "select * from ipv4.20150902 limit 1000"
  },
  "download_paths": [
    "https:\/\/storage.googleapis.com\/censys-bigquery-export\/57f4b90c-0d4d-4109-bd9a-913a20651f16-000000000000.json"
  ]
}
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"}