Jobs API

POST /api/silicon-mark/v1/jobs

Create a new benchmarking job. quick_mark is always included automatically.

Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

Request Body

The request body must be in application/json format.

Field	Type	Required	Description	Constraints
`name`	string	No	Job name (auto-generated if omitted)	Max 60 characters
`description`	string	No	Job description	Max 512 characters
`benchmarks`	array	Yes	List of benchmarks to run. Each item is a benchmark id string or a `{benchmark_id, config}` object. `quick_mark` is always added if not present.	No duplicate (id + config)
`node_count`	integer	No	Number of expected nodes	[ 1 .. 256 ], default 1
`tags`	array	No	Job tags	Max 10 tags, 50 chars each; certain special characters forbidden

Request Example

{
  "name": "GPU Benchmark Test",
  "description": "Testing new cluster",
  "benchmarks": [
    "quick_mark",
    {
      "benchmark_id": "cluster_network",
      "config": {}
    }
  ],
  "node_count": 4,
  "tags": ["production", "gpu"]
}

Responses

201: Created

{
  "id": "7554621440",
  "name": "GPU Benchmark Test",
  "description": "Testing new cluster",
  "node_count": 4,
  "benchmarks": ["quick_mark", "cluster_network"],
  "tags": ["production", "gpu"],
  "token": "eyJ0eXAiOiJKV1Q...",
  "created_at": "2024-03-15T10:30:00Z",
  "expires_at": "2024-03-16T10:30:00Z"
}

400: Bad Request

{
  "error": {
    "code": "PARAMETER_INCORRECT_VALUE",
    "message": "Benchmark 'unknown_benchmark' not found"
  }
}

401: Unauthorized

{
  "error": {
    "code": "CLIENT_TOKEN_INVALID",
    "message": "Invalid or expired token"
  }
}

409: Conflict

{
  "error": {
    "code": "RESOURCE_ALREADY_EXISTS",
    "message": "Job with name 'GPU Test' already exists"
  }
}

GET /api/silicon-mark/v1/jobs

List jobs with filtering and pagination.

Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

Query Parameters

Field	Type	Required	Description	Constraints
`page`	integer	No	Page number	>= 1, default 1
`per_page`	integer	No	Items per page	[ 1 .. 300 ], default 20
`sort_by`	string	No	Field to sort by (`created_at`, `started_at`, `ended_at`, `expires_at`, `name`, `state`, `node_count`, `current_nodes`)	default `created_at`
`sort_order`	string	No	Sort direction	`asc` or `desc`, default `desc`
`state`	string	No	Filter by job state	`created`, `starting`, `running`, `completed`, `aborted`, `failed`, `completed_with_warnings`
`name`	string	No	Filter by name (partial match)	Max 60 characters
`benchmark_id`	string	No	Filter by benchmark in sequence
`tags`	array	No	Filter by tags. Repeat the query param for multiple; a job must include all listed tags.	Max 10
`created_after`	datetime	No	Jobs created after this timestamp	ISO 8601
`created_before`	datetime	No	Jobs created before this timestamp	ISO 8601
`node_count_min`	integer	No	Minimum node count	[ 1 .. 256 ]
`node_count_max`	integer	No	Maximum node count	[ 1 .. 256 ]
`include_results`	boolean	No	Include GPU models and QuickMark aggregate results	default false
`include`	array	No	Optional expansions: `performance`, `performance_nodes` (`performance_nodes` requires `performance`)
`has_performance_data`	boolean	No	When true, only jobs with scoreboard performance data are returned

Responses

200: Successful Response

{
  "results": [
    {
      "id": "7554621440",
      "name": "GPU Benchmark Test",
      "token": "eyJ0eXAiOiJKV1Q...",
      "description": "Testing cluster",
      "state": "completed",
      "node_count": 4,
      "current_nodes": 4,
      "benchmark_sequence": [
        {
          "benchmark_id": "quick_mark",
          "config": null
        },
        {
          "benchmark_id": "cluster_network",
          "config": null
        }
      ],
      "tags": ["production"],
      "created_at": "2024-03-15T10:30:00Z",
      "started_at": "2024-03-15T10:35:00Z",
      "expires_at": "2024-03-16T10:30:00Z",
      "ended_at": "2024-03-15T11:45:00Z",
      "gpu_models": null,
      "quickmark_aggregate_results": null,
      "performance": null,
      "performance_nodes": null,
      "benchmarks": ["quick_mark", "cluster_network"]
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

GET /api/silicon-mark/v1/jobs/tags

Get all unique tags from jobs belonging to the authenticated user. Scope depends on the user’s role (regular users see their own jobs; customer admins see all jobs in their customer; root admins/staff see all jobs).

Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

Responses

200: Successful Response

{
  "tags": ["production", "testing", "gpu-benchmark", "provider: aws"]
}

GET /api/silicon-mark/v1/jobs/stats

Performance tab badge count: the number of jobs whose aggregated performance status is underperforming (same scope as the performance job list).

Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

Query Parameters

Field	Type	Required	Description	Constraints
`benchmark_id`	string	No	Benchmark that drives performance rows	default `quick_mark` (v1 supports `quick_mark` only)
`name`	string	No	Filter by job name
`tags`	array	No	Filter by tags (repeat for multiple; job must include all)
`state`	string	No	Filter by job state	default `completed`
`sort_by`	string	No	Field to sort by	default `created_at`
`sort_order`	string	No	Sort direction	`asc` or `desc`, default `desc`

Responses

200: Successful Response

{
  "alert_job_count": 4
}

GET /api/silicon-mark/v1/jobs/{job_id}

Get detailed information about a specific job. Tasks and all benchmark results are always included.

Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

Path Parameters

Parameter	Type	Required	Description
`job_id`	integer	Yes	The job ID

Responses

200: Successful Response

{
  "id": "7554621440",
  "name": "GPU Benchmark Test",
  "token": "eyJ0eXAiOiJKV1Q...",
  "description": "Testing cluster performance",
  "state": "completed",
  "node_count": 4,
  "current_nodes": 4,
  "benchmark_sequence": [
    { "benchmark_id": "quick_mark", "config": null },
    { "benchmark_id": "cluster_network", "config": null }
  ],
  "tags": ["production"],
  "created_at": "2024-03-15T10:30:00Z",
  "started_at": "2024-03-15T10:35:00Z",
  "expires_at": "2024-03-16T10:30:00Z",
  "ended_at": "2024-03-15T11:45:00Z",
  "benchmarks": ["quick_mark", "cluster_network"],
  "tasks": [
    {
      "id": "7554621441",
      "job_id": "7554621440",
      "machine_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "machine_ip": "192.168.1.10",
      "state": "completed",
      "failed_message": null,
      "created_at": "2024-03-15T10:35:00Z",
      "started_at": "2024-03-15T10:35:30Z",
      "ended_at": "2024-03-15T11:40:00Z",
      "gpu_model": "NVIDIA A100-SXM4-80GB",
      "gpu_count": 8,
      "pdf_report_url": "https://...",
      "benchmark_results": {}
    }
  ],
  "benchmark_results": {
    "cluster_network": {
      "benchmark_id": "cluster_network",
      "benchmark_name": "Cluster Network",
      "started_at": "2024-03-15T10:40:00Z",
      "ended_at": "2024-03-15T10:55:00Z",
      "config": {},
      "results": {
        "avg_bandwidth_gbps": 45.2,
        "avg_latency": 0.8,
        "min_bandwidth_gbps": 42.1,
        "total_links_tested": 12
      },
      "state": "completed",
      "error_message": null
    }
  },
  "pdf_report_url": "https://...",
  "scoreboard_summary": null
}

404: Not Found

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Job with id 7554621440 not found"
  }
}

GET /api/silicon-mark/v1/jobs/{job_id}/results

Get the result summary of this job.

Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

Path Parameters

Parameter	Type	Required	Description
`job_id`	integer	Yes	The job ID

Query Parameters

Field	Type	Required	Description	Constraints
`include_display_names`	boolean	No	Include human-readable field names	default false

Responses

The response is a map keyed by benchmark_id, where each value is a cluster-level benchmark result object.

200: Successful Response

{
  "cluster_network": {
    "benchmark_id": "cluster_network",
    "benchmark_name": "Cluster Network",
    "started_at": "2024-03-15T10:40:00Z",
    "ended_at": "2024-03-15T10:55:00Z",
    "config": {},
    "results": {
      "avg_bandwidth_gbps": 45.2,
      "avg_latency": 0.8,
      "min_bandwidth_gbps": 42.1,
      "total_links_tested": 12,
      "node_count": 4,
      "measurements": []
    },
    "state": "completed",
    "error_message": null
  }
}

DELETE /api/silicon-mark/v1/jobs/delete

Soft-delete a job and all associated tasks. Only the job owner (matching customer_id) can delete their jobs.

Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

Request Body

The request body must be in application/json format.

Field	Type	Required	Description	Constraints
`id`	integer	Yes	Job ID to delete	>= 1

Request Example

{
  "id": 7554621440
}

Responses

200: Job successfully deleted

{
  "message": "Job deleted successfully",
  "requires_agent_stop": false
}

400: Bad Request — job is in a state that prevents deletion (e.g. running)
403: Permission denied — user does not own this job
404: Not Found — job not found

The following job endpoints are intentionally not documented here because they are not customer-facing:

POST /api/silicon-mark/v1/jobs/anonymous — internal anonymous job creation flow.
GET /api/silicon-mark/v1/jobs/current — agent-only; authenticated with a job token, used by the benchmarking agent to fetch its job configuration.
POST /api/silicon-mark/v1/jobs/{job_id}/generate-report — marked INTERNAL TESTING; agent/job-token only.

​Jobs API

​POST /api/silicon-mark/v1/jobs

​Authorization

​Request Body

​Request Example

​Responses

​GET /api/silicon-mark/v1/jobs

​Authorization

​Query Parameters

​Responses

​GET /api/silicon-mark/v1/jobs/tags

​Authorization

​Responses

​GET /api/silicon-mark/v1/jobs/stats

​Authorization

​Query Parameters

​Responses

​GET /api/silicon-mark/v1/jobs/{job_id}

​Authorization

​Path Parameters

​Responses

​GET /api/silicon-mark/v1/jobs/{job_id}/results

​Authorization

​Path Parameters

​Query Parameters

​Responses

​DELETE /api/silicon-mark/v1/jobs/delete

​Authorization

​Request Body

​Request Example

​Responses

Jobs API

POST /api/silicon-mark/v1/jobs

Authorization

Request Body

Request Example

Responses

GET /api/silicon-mark/v1/jobs

Authorization

Query Parameters

Responses

GET /api/silicon-mark/v1/jobs/tags

Authorization

Responses

GET /api/silicon-mark/v1/jobs/stats

Authorization

Query Parameters

Responses

GET /api/silicon-mark/v1/jobs/{job_id}

Authorization

Path Parameters

Responses

GET /api/silicon-mark/v1/jobs/{job_id}/results

Authorization

Path Parameters

Query Parameters

Responses

DELETE /api/silicon-mark/v1/jobs/delete

Authorization

Request Body

Request Example

Responses