---
title: "Read an evidence-qualified model/deployment or separate Bay Run handoff for a task; does not execute."
method: GET
path: "/api/agents/find-runnable"
---

# Read an evidence-qualified model/deployment or separate Bay Run handoff for a task; does not execute.

`GET /api/agents/find-runnable`

## Request

- Base URL: `https://huggingbay.xyz`
- URL: `https://huggingbay.xyz/api/agents/find-runnable`
- Auth: none required

Provide task or its q alias. Unknown tasks return 400 with field and validValues. model (aliases requestedModel, model_name, modelName) is checked first; a different pick is explicitly alternative_for_task. Task accepts plain language (for example: help me write emails); it maps to a task family through a closed keyword list, echoed as taskFamily. For identical inputs the pick matches /api/agents/find-model. selectionPin holds one pick per query for a snapshot (held, promoted when the held pick became unavailable and the best fitting, download-ready alternative replaced it, or unavailable). selectionProvisional true means better-ranked candidates were still being checked; retry for the settled pick. runTested and runKit are exact-file evidence, separate from recorded runReady. Missing/unsupported evidence can produce unavailable or blocked results. Honor nulls, limited availability and commandsAvailable; a next_call does not grant execution authority. Responses are not stored in shared caches.

**Inputs.** Path, query and header fields are listed below. No request body is required.

**Outputs.** See each status below for its media type, schema and headers. A missing record or unavailable capability is not a successful empty result.

**Errors.** API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.

**Rate limits.** Public read budgets apply by client IP and route group. This operation can have a smaller route-specific budget. Read Retry-After on 429 or retryable 503 responses.

## Query parameters

- `task` string
- `q` string
- `commercial` string
- `model` string
- `requestedModel` string
- `model_name` string
- `modelName` string
- `hardware` string
- `ramGb` number
- `gpu` string
- `ctx` integer
- `deviceFamily` string
- `customMemoryGb` number
- `compat` 'containment'

## Response `200`

Qualified candidate, explicit unavailable state or external handoff

- SdkFindRunnable
  - `schemaVersion` string
  - `generatedAt` string
  - `recommendation` SdkRunnableCandidate
    - `artifactId` string
    - `repo` string
    - `task` string
    - `slot` string
    - `executable` boolean
    - `executionAvailable` boolean
    - `commandsAvailable` boolean
    - `next_call` object, nullable
  - `alternatives` SdkRunnableCandidate[]
    - `artifactId` string
    - `repo` string
    - `task` string
    - `slot` string
    - `executable` boolean
    - `executionAvailable` boolean
    - `commandsAvailable` boolean
    - `next_call` object, nullable
  - `next_call` object, nullable
  - `deploymentPlan` SdkDeploymentPlan
    - `schemaVersion` string
    - `available` boolean
    - `artifact` object
      - `id` string
      - `repo` string
      - `revision` string, nullable
      - `task` string
      - `licenseId` string
    - `files` object[]
      - `path` string, required
      - `sha256` string, required
      - `sizeBytes` integer, required
      - `downloadUrl` union
        - string
        - boolean
      - `format` string
      - `role` string
    - `totals` object
      - `hostedFileCount` integer
      - `totalBytes` integer
    - `runTested` boolean
    - `runKit` object, nullable
    - `runtimes` object
    - `verify` object
    - `warnings` string[]
  - `executionAvailable` boolean
  - `commandsAvailable` boolean

## Other responses

- `400`: Missing task or invalid request
- `429`: Rate limited
- `503`: Temporarily unavailable

---

[API](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api.md) · [All operations](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api/revisions/63c474bf0fe4?raw)