Check Analysis Status

GET/v1/file/status/{sha256}

Poll the status of a file analysis job submitted via POST /v1/file/deep. Returns the current pipeline stage and — once complete — the verdict and optionally the full analysis results.

Permission

file:read

Credits

1 per poll

Plans

All plans

Timeout

15 seconds

Path Parameter

Parameter	Type	Description
sha256	string	SHA-256 hash of the file (64 hexadecimal characters). Returned in the `data.sha256` field of the submission response.

Query Parameters

Parameter	Type	Description
include_results	boolean	Set to "true" to include the full analysis_results object in the response. Default: false (status and verdict only).

Response

{
  "data": {
    "sha256": "44d88612fea8a8f36de82e1278abb02f...",
    "status": "complete",
    "verdict": "malicious",
    "file_name": "sample.exe",
    "file_size": 204800,
    "file_type": "pe32",
    "md5": "098f6bcd4621d373cade4e832627b4f6",
    "sha1": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",
    "ssdeep": "768:...",
    "upload_time": "2026-04-14T10:23:01Z",
    "completed_at": "2026-04-14T10:28:14Z",
    "tags": ["apt-campaign", "suspected-loader"],
    "pipeline_stages": [
      { "name": "static", "status": "complete", "duration_ms": 12400 },
      { "name": "dynamic", "status": "complete", "duration_ms": 289000 }
    ]
  },
  "meta": {
    "request_id": "req_b5c6d7e8-...",
    "credits_used": 1,
    "credits_remaining": 464,
    "processing_time_ms": 234
  }
}

Field	Type	Description
data.sha256	string	SHA-256 hash of the analyzed file
data.status	string	"queued", "processing", or "complete"
data.verdict	string \| null	Final verdict once complete: e.g. "malicious", "suspicious", "clean"
data.file_name	string \| null	Original filename as submitted
data.file_size	number \| null	File size in bytes
data.file_type	string \| null	Detected file type (e.g. pe32, pe64, elf, script)
data.md5	string \| null	MD5 hash of the file
data.sha1	string \| null	SHA-1 hash of the file
data.ssdeep	string \| null	Fuzzy hash (ssdeep) for similarity matching
data.upload_time	string \| null	ISO 8601 timestamp of when the file was submitted
data.completed_at	string \| null	ISO 8601 timestamp of when analysis completed (null if still running)
data.tags	string[]	Tags assigned at submission time
data.pipeline_stages	array \| null	Per-stage status objects with name, status, and duration
data.analysis_results	object \| null	Full analysis output. Only present when include_results=true and status is complete
meta.request_id	string	Unique request identifier for support and debugging
meta.credits_used	number	Credits consumed (always 1 per status check)
meta.credits_remaining	number	Remaining credit balance after this request
meta.processing_time_ms	number	Server-side processing time in milliseconds

Code Examples

cURL — Status Check

curl -X GET "https://api.dfir-lab.ch/v1/file/status/44d88612fea8a8f36de82e1278abb02f..." \
  -H "Authorization: Bearer sk-dfir-your-key-here"

cURL — With Full Results

curl -X GET "https://api.dfir-lab.ch/v1/file/status/44d88612fea8a8f36de82e1278abb02f...?include_results=true" \
  -H "Authorization: Bearer sk-dfir-your-key-here"

Python — Polling Loop

import requests
import time

sha256 = "44d88612fea8a8f36de82e1278abb02f..."
headers = {"Authorization": "Bearer sk-dfir-your-key-here"}

while True:
    response = requests.get(
        f"https://api.dfir-lab.ch/v1/file/status/{sha256}",
        headers=headers,
    )
    data = response.json()["data"]

    print(f"Status: {data['status']}")

    if data["status"] == "complete":
        print(f"Verdict: {data['verdict']}")
        break

    # Poll every 15 seconds
    time.sleep(15)

# Fetch full results once complete
response = requests.get(
    f"https://api.dfir-lab.ch/v1/file/status/{sha256}?include_results=true",
    headers=headers,
)
full = response.json()["data"]
print(f"Analysis results: {full.get('analysis_results')}")

Important Notes

Each status poll consumes 1 credit, but only after confirming the sample exists. A 404 sample_not_found response does not deduct credits.
Recommended polling interval: every 15–30 seconds. Polling faster wastes credits without accelerating analysis.
Set include_results=true only once status is "complete" to avoid unnecessary credit usage during pending polls.
The SHA-256 must be exactly 64 hexadecimal characters. Requests with invalid hashes are rejected with 400 invalid_sha256.

Back to File Analyzer API