Skip to main content

aip_sdk.list_runs

aip_sdk.list_runs(project_id: str | None = None, status: RunStatus | None = None, page: int = 1, per_page: int = 20, client: APIClient | None = None, *, metric: str | None = None, metric_config_name: str | None = None, metric_config_version: str | None = None, workspace_id: str | None = None, all_workspaces: bool = False) -> list[RunSummary]

List evaluation runs, newest first.

Reads your session's workspace unless you name one, and raises if none is set. Pass all_workspaces=True to read across every workspace you can access.

Returns a page of run records, optionally filtered by project and status. Each record is a read-only snapshot; pass its id to aip.get_run() to attach to the run and read its results.

Parameters

  • project_id str | None: Only return runs in this project.
  • status RunStatus | None: Only return runs in this status — one of "pending", "claimed", "running", "completed", "retryable_failed", "failed", or "cancelled".
  • page int: Page number (1-based).
  • per_page int: Items per page (1-100).
  • client APIClient | None: Optional API client. Defaults to the module-level client.
  • metric str | None: The metric that metric_config_name/metric_config_version are matched against. Has no filtering effect on its own — pass it together with at least one of them.
  • metric_config_name str | None: Only return runs whose scoring snapshot for metric resolved this metric config name. Requires metric.
  • metric_config_version str | None: Only return runs whose scoring snapshot for metric resolved this metric config version. Requires metric.
  • workspace_id str | None: Only return runs in this workspace.
  • all_workspaces bool: Read across every workspace you can access.

Returns

  • list[RunSummary]: A list of RunSummary objects for the requested page.

Raises

  • InvalidArgumentError: If page/per_page is out of range, if metric is given without metric_config_name or metric_config_version (it would otherwise silently filter nothing), or if either of those is given without metric.
  • AuthError: If no credentials are configured.
  • APIError: If the listing request fails or returns a malformed response.
  • ForbiddenError: If workspace_id names a workspace you cannot access.
  • NoWorkspaceSelectedError: No workspace was passed, none is configured for the session, and all_workspaces was not set.

Examples:

completed = aip.list_runs(status="completed")
for summary in completed:
    print(summary.id, summary.pipeline, summary.status)

page_2 = aip.list_runs(project_id="proj_123", page=2, per_page=50)

tuned = aip.list_runs(metric="agent.custom_judge_rubric", metric_config_name="rubric_prompt_a")