> ## Documentation Index > Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Utilization > Is the hardware busy, are people waiting for it, is the work succeeding. Admin-only: it aggregates across everybody's runs, and the three numbers are about the platform's whole capacity rather than any one person's work. Named for what it reports rather than for what it reports on: a Fleet is a registered set of machines (ADR-0013), and this endpoint is not about one. ## OpenAPI ````yaml /api-reference/openapi.json get /api/utilization openapi: 3.1.0 info: title: StarForge Console description: >- The StarForge control plane. Everything the `sf` CLI and the web console do goes through this API, and so can your own tooling. Authenticate with a bearer token from `POST /api/auth/login` or a CLI device flow; see the Authentication page for how to get one and how long it lasts. version: 0.3.15 servers: - url: https://{host} description: Your StarForge deployment variables: host: default: starforge.your-company.com description: >- The domain your administrator gave you, without a scheme or trailing slash. security: [] tags: - name: auth description: >- Log in, exchange a CLI device code, and inspect the current identity. Everything else on this API needs a bearer token from here. - name: profile description: >- The signed-in user's own account: quota, tokens, preferences, and notification settings. - name: projects description: >- Projects group runs the way `starforge.yaml` names them. A run belongs to exactly one. - name: experiments description: >- Read the experiment definitions the console found in the configured repository. - name: submit description: >- Admit a JobSpec. This is what `sf submit` calls: the catalog handshake, quota check, and preflight all happen here, and a rejection names the gate that refused it. - name: jobs description: >- Everything about a job after it is admitted: status, logs, metrics, samples, artifacts, and the pause/resume/stop controls. - name: runs description: >- Finished work, addressed by run id. A run outlives the job that produced it. - name: ingest description: >- The endpoints training code reports to. `starforge.report` speaks this; you only call it directly when writing an adapter for a framework the catalog does not cover. - name: datasets description: >- Versioned dataset upload, listing, and metadata. Protected datasets expose identity and schema here but never their records. - name: volumes description: Governed directories of files a job may mount read-only. - name: environments description: >- Agent RL environments: their manifests, versions, and upload URLs. A taskset is never returned. - name: benchmarks description: >- The benchmark catalog, the score matrix across runs, and externally scored evaluations. - name: rubrics description: >- Written scoring standards, their revisions, and which runs cited which version. - name: judge description: >- The LLM-judge endpoint a training job calls to score a rollout. OpenAI-compatible. - name: models description: >- The model registry: register a version, promote it, archive it, read its card. - name: model-deployments description: >- Managed model versions serving application traffic: revisions, promotion, rollback, suspension, and deployment tokens. - name: inference description: >- OpenAI-compatible inference against a promoted deployment revision. This is the endpoint applications call. - name: playground description: >- Short-lived serving sessions for human evaluation. Distinct from a deployment: a session expires, a deployment does not. - name: reflow description: >- The governed path from a deployment's production traffic back to the training data of its next version. - name: annotate description: 'Preference annotation: pull a batch, push judgements, read progress.' - name: plugins description: Installed plugins and the extension shelf the console renders. - name: diagnosis description: >- Automated analysis of a finished or failed run, and the accumulated project memory it draws on. - name: approvals description: 'Approval requests: an escalation path, one level deep, with a record.' - name: billing description: >- What the GPU-hours cost. One price on top of the hours the usage page already shows. - name: teams description: 'Teams: the unit capacity is budgeted to. A department, not a tenant.' - name: agent description: >- Submit plans: a proposed submission a human approves or rejects before it becomes a job. - name: share description: >- Public, revocable read-only links to a job or a comparison. The `/api/share/{token}` routes need no bearer token, which is the point. - name: notifications description: The signed-in user's notification feed. - name: search description: Cross-surface search over jobs, runs, datasets, and models. - name: sandbox description: >- Execute model-generated code in a throwaway container with no GPU and no network. - name: uploads description: >- Resumable upload sessions used by dataset, environment, and plugin publishing. - name: integrations-hf description: Hugging Face account linking and repository push. - name: mcp description: Model Context Protocol access information and per-user tool settings. - name: mcp-oauth description: >- OAuth metadata, authorization, token exchange, and dynamic client registration for MCP clients. - name: cluster description: Live capacity and node state across the fleets. - name: fleets description: >- Registered execution backends and the machines in them. Reading is open to every user; creating a fleet, minting a join token and draining a node are admin-only. Joining is authorized by the join token alone. - name: admin description: >- User, role, quota, hardware, schedule, integration, and settings administration. Admin role required. - name: tasks description: >- Scheduled platform maintenance tasks: what they are, when they last ran, and running one now. - name: report description: The rendered daily report page. - name: health description: Liveness and version. Unauthenticated. paths: /api/utilization: get: tags: - cluster summary: Utilization description: >- Is the hardware busy, are people waiting for it, is the work succeeding. Admin-only: it aggregates across everybody's runs, and the three numbers are about the platform's whole capacity rather than any one person's work. Named for what it reports rather than for what it reports on: a Fleet is a registered set of machines (ADR-0013), and this endpoint is not about one. operationId: utilization_api_utilization_get parameters: - name: days in: query required: false schema: type: integer maximum: 180 minimum: 1 default: 30 title: Days responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UtilizationOut' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: UtilizationOut: properties: days: items: $ref: '#/components/schemas/UtilizationDayOut' type: array title: Days default: [] capacity_gpu_hours_per_day: anyOf: - type: number - type: 'null' title: Capacity Gpu Hours Per Day gpu_hours: type: number title: Gpu Hours default: 0 jobs_started: type: integer title: Jobs Started default: 0 succeeded: type: integer title: Succeeded default: 0 failed: type: integer title: Failed default: 0 failure_rate: anyOf: - type: number - type: 'null' title: Failure Rate wait_p50_s: anyOf: - type: number - type: 'null' title: Wait P50 S wait_p95_s: anyOf: - type: number - type: 'null' title: Wait P95 S type: object title: UtilizationOut description: >- What the people who own the GPUs need, rather than what a run's owner does. `capacity_gpu_hours_per_day` is a reference line, never a denominator: it is what one day of the cluster *at its current size* could supply, and nothing records how big the cluster was last Tuesday. Drawing consumption against it gives the utilisation reading without the arithmetic being invented. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError UtilizationDayOut: properties: date: type: string title: Date gpu_hours: type: number title: Gpu Hours default: 0 started: type: integer title: Started default: 0 wait_p50_s: anyOf: - type: number - type: 'null' title: Wait P50 S wait_p95_s: anyOf: - type: number - type: 'null' title: Wait P95 S succeeded: type: integer title: Succeeded default: 0 failed: type: integer title: Failed default: 0 failure_rate: anyOf: - type: number - type: 'null' title: Failure Rate type: object required: - date title: UtilizationDayOut description: One UTC day of fleet activity. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ````