> ## Documentation Index > Fetch the complete documentation index at: https://docs.silicondata.com/llms.txt > Use this file to discover all available pages before exploring further. # Jobs # 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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "error": { "code": "PARAMETER_INCORRECT_VALUE", "message": "Benchmark 'unknown_benchmark' not found" } } ``` * **401**: Unauthorized ```json theme={null} { "error": { "code": "CLIENT_TOKEN_INVALID", "message": "Invalid or expired token" } } ``` * **409**: Conflict ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "id": 7554621440 } ``` ### Responses * **200**: Job successfully deleted ```json theme={null} { "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.