---
title: "List interns"
method: GET
path: "/interns"
tags: ["Interns"]
---

# List interns

`GET /interns`

Lists interns visible to the authenticated key, newest first. Filter by workspace and one or more lifecycle statuses. The API key selects the caller, workspace and visible interns. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.

## Query parameters

- `limit` integer — Maximum number of interns to return, from 1 through 500.
- `status` string[] — Comma-separated lifecycle statuses to include.
- `starting_after` string — The opaque `next_cursor` of the previous page. Returns the interns that come after it in the newest-first order. A malformed cursor is a 400.
- `workspace_id` string, uuid — Only return interns in this workspace. It must match the API key workspace.

## Response `200`

Interns matching the filters.

- InternListResponse — Interns visible to the authenticated API key.
  - `data` Intern[], required
    - `attached_vault_id` string, nullable, required — Vault the intern borrows from another intern, or null when it borrows none.
    - `created_at` string, required — ISO 8601 creation time.
    - `description` string, nullable, required — Free-form description.
    - `hostname` string, nullable, required — Public hostname the intern is reachable at, or null until provisioning has assigned one.
    - `id` string, required — Intern id.
    - `instructions` string, nullable, required — Standing instructions the intern boots with.
    - `last_failure_message` string, nullable, required — Why the last provisioning attempt failed, when status is failed.
    - `model` string, nullable, required — OpenRouter model slug the intern runs, or null for the workspace default.
    - `name` string, required — Intern name, unique per creator within a workspace.
    - `progress` object, nullable, required — Active provisioning step, or null once provisioning has settled.
      - `step_label` string, required — Human-readable label of the active provisioning step.
      - `step_number` integer, required — One-based index of the active step.
      - `total_steps` integer, required — Number of provisioning steps.
    - `status` 'awaiting_slack_install' | 'queued' | 'provisioning' | 'running' | 'failed' | 'stopped' | 'destroying' | 'destroy_failed', required — Lifecycle status.
    - `updated_at` string, required — ISO 8601 last update time.
    - `vault_id` string, nullable, required — Vault the intern owns, or null before it has been created.
    - `workspace_id` string, required — Workspace that owns the intern and scopes its secrets.
  - `has_more` boolean, required — True when more interns match the current filters.
  - `next_cursor` string — Opaque cursor, present when `has_more` is true. Pass it as `starting_after` to fetch the next page.

## Other responses

- `400` — The list filters are invalid.
- `401` — Missing, unknown or provisioning API key.
- `403` — The key owner no longer has access, or the request used a regional hostname.
- `404` — The caller is outside the Intern API programme, the intern is hidden, or lifecycle writes are disabled.
- `408` — The request exceeded its route deadline.
- `500` — The request could not be completed.

## Changes

- **2026-09-19** `b94291e182cc` — 2 info
  - added the new optional `query` request parameter `starting_after`
  - added the optional property `next_cursor` to the response with the `200` status
- **2026-09-18** `c4cafb1919d1` — 7 breaking, 7 info
  - removed the required property `data/items/createdAt` from the response with the `200` status
  - removed the required property `data/items/lastFailureMessage` from the response with the `200` status
  - removed the required property `data/items/progress/stepLabel` from the response with the `200` status
  - removed the required property `data/items/progress/stepNumber` from the response with the `200` status
  - …10 more
- **2026-09-17** `c3b9702bd9d7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/interns/get.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/b94291e182cc?raw)