Analyze

Submit a Sample

POST /api/v1/analyze

Submit a file for detonation in an isolated Windows sandbox.

Request

Content type: multipart/form-data

Field	Type	Required	Description
`file`	File	Yes	The sample to analyze
`duration`	integer	No	Analysis duration in seconds (default: `300`, max: `300`)
`visibility`	string	No	`private` (default) or `public`
`tags`	string	No	JSON array or comma-separated list of tags
`archive_password`	string	No	Password for encrypted archives (ZIP, 7z, RAR)

Example

curl -X POST https://retrace.cloud/api/v1/analyze \
  -H "X-API-Key: rtrc_live_abc123..." \
  -F "[email protected]" \
  -F "duration=300" \
  -F "visibility=private" \
  -F 'tags=["phishing","q4-campaign"]'

Response `200`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "sample": {
    "name": "suspicious.exe",
    "sha256": "a1b2c3d4e5f6...",
    "size": 245760,
    "type": "exe"
  },
  "created_at": "2025-01-15T10:30:00.000Z"
}

List Analyses

GET /api/v1/analyze

Retrieve a paginated list of analyses for your organization.

Query Parameters

Parameter	Type	Default	Description
`status`	string	—	Filter by status: `pending`, `running`, `completed`, `failed`
`sha256`	string	—	Filter by sample SHA-256 hash
`limit`	integer	`20`	Results per page (max: `100`)
`offset`	integer	`0`	Pagination offset

Example

curl "https://retrace.cloud/api/v1/analyze?status=completed&limit=10" \
  -H "X-API-Key: rtrc_live_abc123..."

Response `200`

{
  "analyses": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "sample": {
        "name": "suspicious.exe",
        "sha256": "a1b2c3d4e5f6...",
        "size": 245760,
        "type": "exe"
      },
      "results": {
        "threat_score": 85,
        "verdict": "malicious",
        "event_count": 342
      },
      "visibility": "private",
      "tags": ["phishing", "q4-campaign"],
      "created_at": "2025-01-15T10:30:00.000Z",
      "started_at": "2025-01-15T10:30:05.000Z",
      "completed_at": "2025-01-15T10:35:12.000Z"
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

Get Analysis Details

GET /api/v1/analyze/:id

Retrieve full details for a specific analysis, optionally including events and screenshots.

Query Parameters

Parameter	Type	Description
`include`	string	Repeated param — `events` and/or `screenshots` to include extra data

Example

curl "https://retrace.cloud/api/v1/analyze/550e8400...?include=events&include=screenshots" \
  -H "X-API-Key: rtrc_live_abc123..."

Response `200`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "sample": {
    "name": "suspicious.exe",
    "sha256": "a1b2c3d4e5f6...",
    "md5": "d41d8cd98f00...",
    "sha1": "da39a3ee5e6b...",
    "size": 245760,
    "type": "exe"
  },
  "results": {
    "threat_score": 85,
    "risk_score": 72,
    "verdict": "malicious",
    "iocs": ["185.234.72.10", "evil-domain.com"],
    "mitre_techniques": ["T1059.001", "T1547.001"],
    "event_count": 342,
    "ioc_count": 2,
    "mitre_technique_count": 2,
    "ai_summary": "The sample drops a PowerShell script that..."
  },
  "visibility": "private",
  "tags": ["phishing"],
  "created_at": "2025-01-15T10:30:00.000Z",
  "started_at": "2025-01-15T10:30:05.000Z",
  "completed_at": "2025-01-15T10:35:12.000Z",
  "error_message": null,
  "events": [ ... ],
  "screenshots": [ ... ]
}

The events and screenshots arrays are only present when requested via the include parameter. Events are capped at 5,000 per request.

On this page