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

# Compute Circuit Analytics

> Start an analytics job for a stored circuit.

Use this tool when a circuit has no analytics yet, or only core metrics, and
the workflow needs quality metrics or an evolution snapshot. Haiqu-generated
circuits from data loading, state compression, and transpilation frequently
arrive without advanced analytics computed.

When to Use:
    - Call this when ``get_circuit_by_id`` returns ``analytics: null`` or
      lacks the advanced quality metrics the caller asked about.
    - Call this before comparing a circuit against reference benchmarks.

Constraints:
    - Analytics run asynchronously; this tool returns a job reference, not
      metric values. Poll with ``get_job_results_and_status`` and then read
      the metrics with ``get_circuit_by_id`` or
      ``get_circuit_metrics_evolution``.
    - A pending job for the same circuit and analytics type is reused
      instead of duplicated.

Notes:
    - ``core`` covers qubits, depth, and gate counts; ``advanced`` covers
      the quality metrics compared against reference benchmarks; and
      ``evolution`` records a snapshot for
      ``get_circuit_metrics_evolution``.

Args:
    user: Authenticated user resolved from the API key.
    data: Payload naming the circuit and the analytics family to compute.
    db: Active database session.

Returns:
    A context wrapper naming the analytics job and the next polling step.

Raises:
    HTTPException: Raised with ``404`` when the circuit is not available to
        the caller.



## OpenAPI

````yaml https://api.haiqu.ai/openapi.json post /ai/compute_circuit_analytics
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.5.0
servers: []
security: []
paths:
  /ai/compute_circuit_analytics:
    post:
      summary: Compute Circuit Analytics
      description: >-
        Start an analytics job for a stored circuit.


        Use this tool when a circuit has no analytics yet, or only core metrics,
        and

        the workflow needs quality metrics or an evolution snapshot.
        Haiqu-generated

        circuits from data loading, state compression, and transpilation
        frequently

        arrive without advanced analytics computed.


        When to Use:
            - Call this when ``get_circuit_by_id`` returns ``analytics: null`` or
              lacks the advanced quality metrics the caller asked about.
            - Call this before comparing a circuit against reference benchmarks.

        Constraints:
            - Analytics run asynchronously; this tool returns a job reference, not
              metric values. Poll with ``get_job_results_and_status`` and then read
              the metrics with ``get_circuit_by_id`` or
              ``get_circuit_metrics_evolution``.
            - A pending job for the same circuit and analytics type is reused
              instead of duplicated.

        Notes:
            - ``core`` covers qubits, depth, and gate counts; ``advanced`` covers
              the quality metrics compared against reference benchmarks; and
              ``evolution`` records a snapshot for
              ``get_circuit_metrics_evolution``.

        Args:
            user: Authenticated user resolved from the API key.
            data: Payload naming the circuit and the analytics family to compute.
            db: Active database session.

        Returns:
            A context wrapper naming the analytics job and the next polling step.

        Raises:
            HTTPException: Raised with ``404`` when the circuit is not available to
                the caller.
      operationId: compute_circuit_analytics
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextComputeAnalyticsModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextAnalyticsJobModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    ContextComputeAnalyticsModel:
      properties:
        circuit_id:
          type: string
          title: Circuit Id
        analytics_type:
          type: string
          enum:
            - core
            - advanced
            - evolution
          title: Analytics Type
          description: >-
            Analytics family to compute. Use `core` for qubits, depth, and gate
            counts, `advanced` for the quality metrics used against reference
            benchmarks (program communication, critical depth, entanglement
            ratio, parallelism, liveness), and `evolution` to record a metrics
            snapshot readable through `get_circuit_metrics_evolution`.
          default: advanced
      type: object
      required:
        - circuit_id
      title: ContextComputeAnalyticsModel
      description: |-
        Define payload for explicitly triggering circuit analytics computation.

        Attributes:
            circuit_id: Circuit to analyze.
            analytics_type: Analytics family to compute.
      examples:
        - analytics_type: advanced
          circuit_id: circ-123
        - analytics_type: evolution
          circuit_id: circ-123
    ContextAnalyticsJobModel:
      properties:
        context:
          type: string
          title: Context
      type: object
      required:
        - context
      title: ContextAnalyticsJobModel
      description: |-
        Represent context returned after requesting analytics computation.

        Attributes:
            context: Summary of the submission and the next polling step. Analytics
                run asynchronously, so this response does not carry metric values.
    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

````