---
title: "List Models"
method: GET
path: "/v1/models"
tags: ["Models"]
---

# List Models

`GET /v1/models`

## Request

- Base URL: `https://api.ensemble.markets` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ensemble.markets/v1/models`
- Auth: HTTP bearer

The caller's models, newest first. Favorites, labels and status filter the complete library before pagination.

## Query parameters

- `status` string, nullable: Only programs in this status: building, active, updating, paused or failed
- `is_favorite` boolean, nullable: Only favorited (true) or unfavorited (false) models; omit for all
- `labels` string[]: Match any of these private labels, case-insensitively; combines with status and is_favorite
- `limit` integer: Rows per page
- `offset` integer: Rows to skip

## Response `200`

Successful Response

- ModelSummaryPage
  - `data` ModelSummary[], required
    - `id` string, required: Model ID (model_... or legacy m-...)
    - `name` string, nullable: May be null if the build failed before naming
    - `symbol` string, nullable: May be null if the build failed before naming
    - `status` 'building' | 'active' | 'updating' | 'paused' | 'blocked' | 'failed', required: building: no results yet; active: results served and refreshed nightly; updating: a rebuild or refresh is running (results keep serving); blocked: updates await a failed or unavailable dependency; paused: results served, nightly refresh off; failed: the build never produced a usable model
    - `run` ModelActivity: What is running against the model right now. Null when idle.
      - `kind` 'build' | 'rebuild' | 'run', required: build: first build; rebuild: new implementation from a prompt or script; run: the stored script against new market data (a default run that will go live)
      - `status` 'queued' | 'running', required
      - `stage` string, required: Human-readable current stage, e.g. 'Backtesting'
      - `stage_id` 'n1_security_screening' | 'n1b_universe_resolution' | 'n2_code_generation' | 'n3_code_validation' | 'n4_modal_execution' | 'n5_result_qa', nullable: Pipeline stage id; null for a run
      - `attempt` integer
      - `max_attempts` integer
      - `started_at` string, date-time, nullable
      - `updated_at` string, date-time, nullable
      - `stages` ModelActivityStage[]: Per-stage detail for a build or rebuild; empty for a run
        - `id` 'n1_security_screening' | 'n1b_universe_resolution' | 'n2_code_generation' | 'n3_code_validation' | 'n4_modal_execution' | 'n5_result_qa', required
        - `status` 'pending' | 'running' | 'completed' | 'error', required
        - `attempt` integer
        - `duration_seconds` number, nullable
    - `warning` string, nullable: Something went wrong without changing the status: a failed rebuild, a paused auto-update, or overdue data
    - `depth` integer: 0 when the model holds assets only; otherwise one more than its deepest member
    - `structure` ModelStructure: What the model's whole tree resolves to.
      - `models` integer: Distinct models below this one, at every level
      - `assets` integer: Distinct tickers the tree ultimately holds (cash excluded)
    - `as_of` string, date, nullable: Last market session covered by the results
    - `auto_update` boolean: Whether the nightly refresh is on
    - `refresh` ModelRefresh: Present freshness, independent of the last run's historical outcome.
      - `state` 'current' | 'disabled' | 'pending' | 'running' | 'waiting' | 'retrying' | 'blocked', required
      - `requested_session` string, date, nullable
      - `next_retry` string, date-time, nullable
      - `blockers` ModelRefreshBlocker[]
        - `model_id` string, required
        - `name` string, required
        - `reason_code` string, required
        - `reason` string, required
        - `run_id` string, nullable
    - `is_public` boolean, required
    - `is_favorite` boolean, nullable: Owner's favorite state; null for non-owner readers
    - `labels` string[], nullable: Owner's private organizational labels; null for non-owner readers
    - `url` string, nullable: Tear sheet URL; set once the model has built
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `total` integer, required: Rows matching the filters, across every page

## Other responses

- `4XX`: The request was refused; `error.type` says why
- `5XX`: The server failed; quote `X-Request-Id` when reporting it

---

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