> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Experiments Mcp

> List all experiments owned by the authenticated user.

In Haiqu, an experiment is the top-level persistent workflow container for
a user's quantum work. It groups related circuits, derived jobs, metrics,
artifacts, and MCP context under one ``experiment_id`` so later tools can
operate on the same workflow state.

Use this tool when the caller needs to discover available experiments before
selecting one for inspection or updates. The result only includes
caller-owned experiments, and an empty list is a valid outcome.

When to Use:
    - Call this before other experiment-scoped MCP tools when the caller
      does not yet know the right ``experiment_id``.
    - Call this to audit available workspaces or discover stale experiments
      that may need follow-up.

Constraints:
    - Only experiments owned by the authenticated caller are returned.
    - An empty list is a valid result.

Notes:
    - Returned ``id`` values can be passed directly to experiment, circuit,
      job, and artifact MCP endpoints.
    - For agent-facing output, prefer a concise list of ``id`` and
      ``name`` pairs instead of dumping every field when many experiments
      exist.

Args:
    user: Authenticated user resolved from the API key.
    db: Active database session.

Returns:
    All experiments visible to the authenticated caller.



## OpenAPI

````yaml https://api.haiqu.ai/openapi.json get /ai/
openapi: 3.1.0
info:
  title: Haiqu API
  summary: Haiqu RESTful API service.
  description: Cloud service providing the access to Haiqu cloud runtime
  contact:
    name: Haiqu Inc.
    url: https://haiqu.ai/
    email: info@haiqu.ai
  version: 1.4.0
servers: []
security: []
paths:
  /ai/:
    get:
      summary: List Experiments Mcp
      description: >-
        List all experiments owned by the authenticated user.


        In Haiqu, an experiment is the top-level persistent workflow container
        for

        a user's quantum work. It groups related circuits, derived jobs,
        metrics,

        artifacts, and MCP context under one ``experiment_id`` so later tools
        can

        operate on the same workflow state.


        Use this tool when the caller needs to discover available experiments
        before

        selecting one for inspection or updates. The result only includes

        caller-owned experiments, and an empty list is a valid outcome.


        When to Use:
            - Call this before other experiment-scoped MCP tools when the caller
              does not yet know the right ``experiment_id``.
            - Call this to audit available workspaces or discover stale experiments
              that may need follow-up.

        Constraints:
            - Only experiments owned by the authenticated caller are returned.
            - An empty list is a valid result.

        Notes:
            - Returned ``id`` values can be passed directly to experiment, circuit,
              job, and artifact MCP endpoints.
            - For agent-facing output, prefer a concise list of ``id`` and
              ``name`` pairs instead of dumping every field when many experiments
              exist.

        Args:
            user: Authenticated user resolved from the API key.
            db: Active database session.

        Returns:
            All experiments visible to the authenticated caller.
      operationId: list_experiments
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ContextExperimentModel'
                type: array
                title: Response List Experiments
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    ContextExperimentModel:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          default: ''
        creation_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Creation Date
        tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Tags
          default: ''
        circuits_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Circuits Count
          default: 0
        jobs_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Jobs Count
          default: 0
        last_action_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Action Date
        context:
          type: string
          title: Context
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          default: ''
      type: object
      required:
        - id
        - name
        - context
      title: ContextExperimentModel
      description: |-
        Represent an experiment with MCP-specific context metadata.

        ``description`` and ``creation_date`` remain optional for compatibility
        with legacy database rows.

        Attributes:
            description: Plain-text experiment description. Optional for legacy
                rows that still store ``NULL``.
            creation_date: Experiment creation timestamp. Optional for legacy rows
                that still store ``NULL``.
            context: Additional plain-text guidance for AI agents consuming the
                experiment.
            url: Dashboard URL for the experiment when available.
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: HAIQU_API_KEY
    APIKeyHeader:
      type: apiKey
      in: header
      name: authorization

````