---
updatedAt: 2026-04-21T17:11:35.000Z
agentTools:
projectIndex: https://docs.censys.com/llms.txt
---
# Get scan status
Retrieve the current status of a scan by its ID. This endpoint works for both [Live Discovery scans](https://docs.censys.com/reference/v3-threathunting-scans-discovery#/) and [Live Rescans](https://docs.censys.com/reference/v3-globaldata-scans-rescan#/).
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.
# OpenAPI definition
```json
{
"components": {
"schemas": {
"AuthenticationError": {
"additionalProperties": false,
"properties": {
"error": {
"$ref": "#/components/schemas/AuthenticationErrorDetail",
"description": "Detailed information about the authentication error"
}
},
"type": "object"
},
"AuthenticationErrorDetail": {
"additionalProperties": false,
"properties": {
"code": {
"description": "HTTP status code",
"examples": [
401
],
"format": "int64",
"type": "integer"
},
"message": {
"description": "Human-readable message describing the error occurrence",
"examples": [
"Access credentials are invalid"
],
"type": "string"
},
"reason": {
"description": "Human-readable explanation of the underlying cause of the error",
"examples": [
"Access token is not active"
],
"type": "string"
},
"request": {
"type": "string"
},
"status": {
"description": "HTTP status message associated with the error",
"examples": [
"Unauthorized"
],
"type": "string"
}
},
"type": "object"
},
"ErrorDetail": {
"additionalProperties": false,
"properties": {
"location": {
"description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'",
"type": "string"
},
"message": {
"description": "Error message text",
"type": "string"
},
"value": {
"description": "The value at the given location"
}
},
"type": "object"
},
"ErrorModel": {
"additionalProperties": false,
"properties": {
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"examples": [
"Property foo is required but is missing."
],
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"type": [
"array",
"null"
]
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"examples": [
"https://example.com/error-log/abc123"
],
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"examples": [
400
],
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"examples": [
"Bad Request"
],
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"examples": [
"https://example.com/errors/example"
],
"format": "uri",
"type": "string"
}
},
"type": "object"
},
"ResponseEnvelopeTrackedScan": {
"additionalProperties": false,
"properties": {
"result": {
"$ref": "#/components/schemas/TrackedScan"
}
},
"type": "object"
},
"ServiceId": {
"additionalProperties": false,
"properties": {
"ip": {
"type": "string"
},
"port": {
"format": "int32",
"minimum": 0,
"type": "integer"
},
"protocol": {
"type": "string"
},
"transport_protocol": {
"enum": [
"",
"tcp",
"udp",
"icmp",
"quic"
],
"type": "string"
}
},
"type": "object"
},
"TrackedScan": {
"additionalProperties": false,
"properties": {
"completed": {
"type": "boolean"
},
"create_time": {
"type": "string"
},
"target": {
"$ref": "#/components/schemas/TrackedScan_ScanTarget"
},
"tasks": {
"items": {
"$ref": "#/components/schemas/TrackedScan_Task"
},
"type": [
"array",
"null"
]
},
"tracked_scan_id": {
"type": "string"
}
},
"type": "object"
},
"TrackedScan_ScanTarget": {
"additionalProperties": false,
"properties": {
"host_port": {
"$ref": "#/components/schemas/TrackedScan_ScanTarget_HostPort"
},
"hostname_port": {
"$ref": "#/components/schemas/TrackedScan_ScanTarget_HostnamePort"
},
"service_id": {
"$ref": "#/components/schemas/ServiceId"
},
"web_origin": {
"$ref": "#/components/schemas/WebOrigin"
}
},
"type": "object"
},
"TrackedScan_ScanTarget_HostPort": {
"additionalProperties": false,
"properties": {
"ip": {
"type": "string"
},
"port": {
"format": "int32",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"TrackedScan_ScanTarget_HostnamePort": {
"additionalProperties": false,
"properties": {
"hostname": {
"type": "string"
},
"port": {
"format": "int32",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"TrackedScan_Task": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"status": {
"enum": [
"",
"scanning",
"scanned",
"rejected",
"timed_out",
"completed",
"ignored"
],
"type": "string"
},
"update_time": {
"type": "string"
}
},
"type": "object"
},
"WebOrigin": {
"additionalProperties": false,
"properties": {
"hostname": {
"type": "string"
},
"port": {
"format": "int32",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
}
},
"securitySchemes": {
"PersonalAccessToken": {
"description": "Your Censys personal access token. These are managed in your [Account Settings](https://accounts.censys.io/settings/personal-access-tokens)",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"contact": {
"email": "support@censys.com",
"name": "Censys Inc.",
"url": "https://censys.com"
},
"title": "Censys Platform API",
"version": "1.0.151"
},
"openapi": "3.1.0",
"paths": {
"/v3/threat-hunting/scans/{scan_id}": {
"get": {
"description": "Retrieve the current status of a scan by its ID. This endpoint works for both [Live Discovery scans](https://docs.censys.com/reference/v3-threathunting-scans-discovery#/) and [Live Rescans](https://docs.censys.com/reference/v3-globaldata-scans-rescan#/).
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.",
"operationId": "v3-threathunting-scans-get",
"parameters": [
{
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.",
"explode": false,
"in": "query",
"name": "organization_id",
"required": true,
"schema": {
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.",
"examples": [
"11111111-2222-3333-4444-555555555555"
],
"format": "uuid",
"type": "string"
}
},
{
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.",
"in": "header",
"name": "X-Organization-ID",
"schema": {
"description": "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.",
"examples": [
"11111111-2222-3333-4444-555555555555"
],
"format": "uuid",
"type": "string"
},
"x-speakeasy-ignore": true
},
{
"description": "The unique identifier of the tracked scan",
"in": "path",
"name": "scan_id",
"required": true,
"schema": {
"description": "The unique identifier of the tracked scan",
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/vnd.censys.api.v3.trackedscan.v1+json": {
"schema": {
"$ref": "#/components/schemas/ResponseEnvelopeTrackedScan"
}
}
},
"description": "OK",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
},
"X-Request-ID": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Bad request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationError"
}
}
},
"description": "Request does not contain a valid Authorization token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "User does not have permission to access this data"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "No scan found"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Internal server error"
}
},
"security": [
{
"PersonalAccessToken": []
}
],
"summary": "Get scan status",
"tags": [
"Threat Hunting"
],
"x-speakeasy-name-override": "GetTrackedScanThreatHunting"
}
}
},
"servers": [
{
"description": "The Censys Platform API",
"url": "https://api.platform.censys.io"
}
],
"tags": [
{
"description": "Endpoints related to the Adversary Investigation product",
"name": "Threat Hunting"
}
],
"x-readme": {
"parameter-ordering": [
"path",
"body",
"query",
"cookie",
"form",
"header"
],
"samples-languages": [
"shell",
"python",
"go",
"javascript",
"java"
]
},
"x-speakeasy-globals": {
"parameters": [
{
"in": "query",
"name": "organization_id",
"schema": {
"type": "string"
}
}
]
}
}
```