> ## 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.

# Get Experiment By Name

> Return one caller-owned experiment by exact name.

Use this tool when the caller already knows the exact experiment name and
wants the full experiment object. Name matching is exact and scoped to the
authenticated user, so the route does not perform fuzzy lookup across other
users' experiments.

When to Use:
    - Call this when the workflow is keyed by a user-provided experiment
      name rather than a stored ID.
    - Call this when the caller needs the full experiment payload, not just
      the dashboard URL.

Constraints:
    - Name matching is exact.
    - The route only searches the authenticated user's experiments.

Args:
    user: Authenticated user resolved from the API key.
    db: Active database session.
    experiment_name: Exact experiment name to resolve.

Returns:
    The matching experiment object with MCP context fields populated.

Raises:
    HTTPException: Raised with ``404`` when no caller-owned experiment with
        the requested name exists.



## OpenAPI

````yaml https://api.haiqu.ai/openapi.json get /ai/by_name/{experiment_name}
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/by_name/{experiment_name}:
    get:
      summary: Get Experiment By Name
      description: >-
        Return one caller-owned experiment by exact name.


        Use this tool when the caller already knows the exact experiment name
        and

        wants the full experiment object. Name matching is exact and scoped to
        the

        authenticated user, so the route does not perform fuzzy lookup across
        other

        users' experiments.


        When to Use:
            - Call this when the workflow is keyed by a user-provided experiment
              name rather than a stored ID.
            - Call this when the caller needs the full experiment payload, not just
              the dashboard URL.

        Constraints:
            - Name matching is exact.
            - The route only searches the authenticated user's experiments.

        Args:
            user: Authenticated user resolved from the API key.
            db: Active database session.
            experiment_name: Exact experiment name to resolve.

        Returns:
            The matching experiment object with MCP context fields populated.

        Raises:
            HTTPException: Raised with ``404`` when no caller-owned experiment with
                the requested name exists.
      operationId: get_experiment_by_name
      parameters:
        - name: experiment_name
          in: path
          required: true
          schema:
            type: string
            title: Experiment Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextExperimentModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: HAIQU_API_KEY
    APIKeyHeader:
      type: apiKey
      in: header
      name: authorization

````