Runs (Scans)

Create a New Scan

Execute a workflow against a target. Basic scan with flow workflow:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "subdomain-enum",
    "target": "example.com"
  }'

Basic scan with module workflow:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "module": "port-scan",
    "target": "example.com"
  }'

Scan with custom parameters:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "subdomain-enum",
    "target": "example.com",
    "params": {
      "threads": "50",
      "timeout": "30"
    }
  }'

Scan with priority and timeout:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "subdomain-enum",
    "target": "example.com",
    "priority": "high",
    "timeout": 60
  }'

Scan with Docker runner:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "subdomain-enum",
    "target": "example.com",
    "runner_type": "docker",
    "docker_image": "osmedeus/osmedeus:latest"
  }'

Scan with SSH runner:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "subdomain-enum",
    "target": "example.com",
    "runner_type": "ssh",
    "ssh_host": "worker1.example.com"
  }'

Request Body Parameters:

Parameter	Type	Required	Default	Description
`flow`	string	No*	-	Flow workflow name to execute
`module`	string	No*	-	Module workflow name to execute
`target`	string	No**	-	Single target to scan
`targets`	array	No**	-	Multiple targets to scan
`target_file`	string	No**	-	Path to file containing targets
`params`	object	No	`{}`	Custom workflow parameters
`priority`	string	No	`normal`	Priority level: `low`, `normal`, `high`, `critical`
`timeout`	int	No	-	Timeout in minutes for the run
`concurrency`	int	No	1	Number of concurrent targets
`runner_type`	string	No	`host`	Execution environment: `host`, `docker`, `ssh`
`docker_image`	string	No	-	Docker image for docker runner
`ssh_host`	string	No	-	SSH host for ssh runner
`workspace`	string	No	auto	Custom workspace name

* One of flow or module is required. ** One of target, targets, or target_file is required. Response:

{
  "message": "Run started",
  "workflow": "subdomain-enum",
  "kind": "flow",
  "target": "example.com",
  "target_count": 1,
  "priority": "normal",
  "job_id": "a1b2c3d4",
  "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "poll_url": "/osm/api/jobs/a1b2c3d4",
  "runner_type": "docker",
  "timeout": 60
}

Multi-Target Scanning

Scan multiple targets with concurrency control:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "subdomain-enum",
    "targets": ["example.com", "test.com", "demo.com"],
    "concurrency": 3
  }'

Response:

{
  "message": "Run started",
  "workflow": "subdomain-enum",
  "kind": "flow",
  "target_count": 3,
  "targets": ["example.com", "test.com", "demo.com"],
  "concurrency": 3,
  "priority": "normal",
  "job_id": "b2c3d4e5",
  "status": "queued",
  "poll_url": "/osm/api/jobs/b2c3d4e5"
}

Scan from Uploaded Target File

Use an uploaded target file (from /osm/api/upload-file) for running:

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "module": "port-scan",
    "target_file": "/home/user/osmedeus-base/data/uploads/targets.txt",
    "concurrency": 5
  }'

This is similar to CLI’s -T flag: osmedeus run -m port-scan -T targets.txt

List Runs

Get a paginated list of all runs.

curl http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN"

Query Parameters:

Parameter	Type	Default	Description
`status`	string	-	Filter by status: `pending`, `running`, `completed`, `failed`
`workflow_name`	string	-	Filter by workflow name
`target`	string	-	Filter by target
`offset`	int	0	Pagination offset
`limit`	int	20	Maximum records to return

Response:

{
  "data": [
    {
      "id": 1,
      "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "workflow_name": "subdomain-enum",
      "workflow_kind": "flow",
      "target": "example.com",
      "params": {"threads": "50"},
      "status": "running",
      "workspace": "example.com",
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": null,
      "total_steps": 10,
      "completed_steps": 3,
      "current_pid": 12345,
      "trigger_type": "manual",
      "run_group_id": "a1b2c3d4",
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:03:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "offset": 0,
    "limit": 20
  }
}

Note: The current_pid field shows the process ID of the currently running command. This can be used to identify and cancel the running process. When the run completes, this field is cleared (set to 0 or omitted).

Get Run Details

Get details of a specific run by ID.

curl http://localhost:8002/osm/api/runs/run-abc123 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": {
    "id": 1,
    "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "workflow_name": "subdomain-enum",
    "workflow_kind": "flow",
    "target": "example.com",
    "params": {"threads": "50"},
    "status": "completed",
    "workspace": "example.com",
    "started_at": "2025-01-15T10:00:00Z",
    "completed_at": "2025-01-15T10:30:00Z",
    "error_message": "",
    "schedule_id": "",
    "trigger_type": "manual",
    "trigger_name": "",
    "run_group_id": "a1b2c3d4",
    "total_steps": 10,
    "completed_steps": 10,
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Note: You can use either the numeric id or the run_uuid to fetch run details.

Cancel Run

Cancel a running workflow execution. This will terminate all running processes associated with the run.

# Cancel by run_uuid
curl -X DELETE http://localhost:8002/osm/api/runs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

# Or cancel by numeric id
curl -X DELETE http://localhost:8002/osm/api/runs/1 \
  -H "Authorization: Bearer $TOKEN"

Response (processes killed successfully):

{
  "message": "Run cancelled successfully",
  "id": 1,
  "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "killed_pids": [12345, 12346],
  "processes_terminated": 2,
  "kill_method": "registry"
}

Response (using database PID fallback):

{
  "message": "Run cancelled successfully",
  "id": 1,
  "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "killed_pids": [12345],
  "processes_terminated": 1,
  "kill_method": "database_pid"
}

Response (no active processes found):

{
  "message": "Run cancelled successfully",
  "id": 1,
  "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "note": "No active processes found to terminate; database status updated"
}

Kill Methods:

registry - Processes were tracked in memory and killed via the run registry (API-initiated runs)
database_pid - Process was killed using the PID stored in the database (fallback method)

Get Run Steps

Get all step results for a specific run.

# Using run_uuid
curl http://localhost:8002/osm/api/runs/550e8400-e29b-41d4-a716-446655440000/steps \
  -H "Authorization: Bearer $TOKEN"

# Or using numeric id
curl http://localhost:8002/osm/api/runs/1/steps \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "run_id": 1,
      "step_name": "run-subfinder",
      "step_type": "bash",
      "status": "completed",
      "command": "subfinder -d example.com -o subdomains.txt",
      "output": "Found 150 subdomains",
      "error_message": "",
      "exports": {"subdomains_file": "subdomains.txt"},
      "duration_ms": 45000,
      "log_file": "/workspaces/example.com/logs/run-subfinder.log",
      "started_at": "2025-01-15T10:01:00Z",
      "completed_at": "2025-01-15T10:01:45Z",
      "created_at": "2025-01-15T10:01:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "run_id": 1,
      "step_name": "run-httpx",
      "step_type": "bash",
      "status": "completed",
      "command": "httpx -l subdomains.txt -o alive.txt",
      "output": "Probed 150 hosts, 89 alive",
      "error_message": "",
      "exports": {"alive_file": "alive.txt"},
      "duration_ms": 120000,
      "log_file": "/workspaces/example.com/logs/run-httpx.log",
      "started_at": "2025-01-15T10:01:45Z",
      "completed_at": "2025-01-15T10:03:45Z",
      "created_at": "2025-01-15T10:01:45Z"
    }
  ]
}

Get Run Artifacts

Get all output artifacts for a specific run.

# Using run_uuid
curl http://localhost:8002/osm/api/runs/550e8400-e29b-41d4-a716-446655440000/artifacts \
  -H "Authorization: Bearer $TOKEN"

# Or using numeric id
curl http://localhost:8002/osm/api/runs/1/artifacts \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "run_id": 1,
      "workspace": "example.com",
      "name": "subdomains.txt",
      "artifact_path": "/workspaces/example.com/subdomains.txt",
      "artifact_type": "output",
      "content_type": "txt",
      "size_bytes": 4523,
      "line_count": 150,
      "description": "Discovered subdomains",
      "created_at": "2025-01-15T10:01:45Z"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "run_id": 1,
      "workspace": "example.com",
      "name": "alive.txt",
      "artifact_path": "/workspaces/example.com/alive.txt",
      "artifact_type": "output",
      "content_type": "txt",
      "size_bytes": 2890,
      "line_count": 89,
      "description": "Alive HTTP endpoints",
      "created_at": "2025-01-15T10:03:45Z"
    },
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
      "run_id": 1,
      "workspace": "example.com",
      "name": "nuclei-results.json",
      "artifact_path": "/workspaces/example.com/nuclei-results.json",
      "artifact_type": "output",
      "content_type": "json",
      "size_bytes": 15234,
      "line_count": 45,
      "description": "Nuclei vulnerability scan results",
      "created_at": "2025-01-15T10:15:00Z"
    }
  ]
}

Artifact Types:

report - Generated reports from the workflow’s reports section
state_file - State files like run-state.json, run-execution.log
output - General output files from steps
screenshot - Screenshots captured during the scan

Content Types:

json, jsonl, yaml, html, md, log, pdf, png, txt, zip, folder, unknown

Duplicate Run

Create a copy of an existing run with the same configuration.

curl -X POST http://localhost:8002/osm/api/runs/550e8400-e29b-41d4-a716-446655440000/duplicate \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "message": "Run duplicated",
  "original_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "new_run_uuid": "660e8400-e29b-41d4-a716-446655440001",
  "status": "pending"
}

Start Run

Start a pending run that was created but not yet started.

curl -X POST http://localhost:8002/osm/api/runs/550e8400-e29b-41d4-a716-446655440000/start \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "message": "Run started",
  "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running"
}

Get Job Status

Get the status of a job (a group of runs from the same request). This is useful for tracking multi-target scans.

curl http://localhost:8002/osm/api/jobs/a1b2c3d4 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "job_id": "a1b2c3d4",
  "total_runs": 3,
  "completed": 2,
  "running": 1,
  "failed": 0,
  "pending": 0,
  "runs": [
    {
      "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "target": "example.com",
      "status": "completed"
    },
    {
      "run_uuid": "550e8400-e29b-41d4-a716-446655440001",
      "target": "test.com",
      "status": "completed"
    },
    {
      "run_uuid": "550e8400-e29b-41d4-a716-446655440002",
      "target": "demo.com",
      "status": "running"
    }
  ]
}

Priority Levels

Runs can be assigned a priority level to control execution order when multiple runs are queued.

Priority	Description
`low`	Lowest priority, processed last
`normal`	Default priority (used when not specified)
`high`	Higher priority, processed before normal/low
`critical`	Highest priority, processed first

Note: Priority defaults to normal when not specified in the request

Getting Started

Advanced Usage

Understand Architecture

Workflows

Functions

Cloud

Advanced Topics & Extending Osmedeus

Reference

Runs

Runs (Scans)

Create a New Scan

Multi-Target Scanning

Scan from Uploaded Target File

List Runs

Get Run Details

Cancel Run

Get Run Steps

Get Run Artifacts

Duplicate Run

Start Run

Get Job Status

Priority Levels

Getting Started

Advanced Usage

Understand Architecture

Workflows

Functions

Cloud

Advanced Topics & Extending Osmedeus

Reference

Documentation Index

​Runs (Scans)

​Create a New Scan

​Multi-Target Scanning

​Scan from Uploaded Target File

​List Runs

​Get Run Details

​Cancel Run

​Get Run Steps

​Get Run Artifacts

​Duplicate Run

​Start Run

​Get Job Status

​Priority Levels

Runs (Scans)

Create a New Scan

Multi-Target Scanning

Scan from Uploaded Target File

List Runs

Get Run Details

Cancel Run

Get Run Steps

Get Run Artifacts

Duplicate Run

Start Run

Get Job Status

Priority Levels