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

# API to fetch metrics used to plot monitoring charts

> API to fetch metrics used to plot monitoring charts



## OpenAPI

````yaml POST /v3/queries
openapi: 3.0.3
info:
  title: Fiddler API - 2.0
  description: APIs to interact with Fiddler
  termsOfService: https://fiddler.ai/about/terms
  contact:
    email: support@fiddler.ai
  license:
    name: Proprietary
    url: '2.0'
  version: '2.0'
servers: []
security:
  - BearerAuth: []
tags:
  - name: access-key
    description: CRUD operations for API keys
  - name: span-v3
  - name: aggregation-invalidation-request-v3
    description: Endpoints related to retrieving aggregation invalidation requests
  - name: alert-rules-v3
    description: CRUD for Alert Rules, Summary, and Stats APIs
  - name: application-v3
  - name: attribute-v3
  - name: auth
    description: Authentication strategies and login flows
  - name: baseline-v3
    description: CRUD for baseline
  - name: catalog-v3
    description: >-
      Entity catalog provides paginated, searchable discovery of entity names
      (attribute keys, agent names, span types, span names) and their distinct
      values. Powered by ClickHouse materialized views — no worker or PostgreSQL
      dependency.
  - name: chart-annotation-v3
    description: Endpoints related to retrieving chart annotations
  - name: chart-v3
    description: CRUD for chart
  - name: queries-v3
    description: v3 queries API
  - name: configuration-v3
    description: CRUD for configurations
  - name: custom-metrics-v3
  - name: dimensionality-reduction-v3
  - name: environment-v3
    description: Endpoints related to environment management
  - name: evals
  - name: datasets
  - name: evaluation-v3
  - name: evaluator-v3
  - name: rule-evaluators-v3
  - name: experiment-v3
  - name: explainability-v3
  - name: llm_rca-v3
  - name: file-upload
    description: Endpoints related to file uploading.
  - name: fql-expressions-v3
    description: >
      Endpoints for listing FQL (Fiddler Query Language) functions available for
      GenAI custom metrics. Used by the frontend for autocomplete and signature
      hints in the FQL editor.
  - name: genai-alert-rules-v3
    description: CRUD API for GenAI Alert Rules
  - name: genai-custom-metrics-v3
    description: API for GenAI Custom Metrics
  - name: genai-metrics-v3
    description: >-
      Endpoints for pre-aggregated GenAI metrics. All metric data is
      pre-aggregated by an hourly ClickHouse refreshable materialized view; no
      real-time aggregation is performed at request time.
  - name: guardrails-api
    description: Endpoints related to retrieving Guardrails specific data
  - name: ingestion-v3
  - name: intercom-api
    description: Endpoints related to intercom APIs
  - name: jobs-v3
  - name: llm-gateway-v3
  - name: auth-login
  - name: auth-logout
  - name: metrics-v3
    description: Metrics endpoints
  - name: model-v3
  - name: dashboard-v3
  - name: model-deployment-v3
  - name: monitoring-summary-v3
  - name: histograms-v3
  - name: organization-roles-v3
    description: Update user org role
  - name: organization-settings-v3
    description: Update organization settings such as timezone, email configuration, etc.
  - name: pagerduty-api
    description: CRUD for Pagerduty services.
  - name: project-v3
  - name: project-roles-v3
    description: Project role assignment management
  - name: searchable-text-key-v3
    description: >-
      Manage the global searchable text keys table that controls which OTel
      attribute keys are routed to the full-text-searchable `ValueContent`
      column in the unified attributes table. Changes propagate to the backing
      ClickHouse dictionary within 1-2 minutes and affect all tenants.
  - name: segments-v3
  - name: semantic-mapping-v3
    description: >-
      Manage the global semantic name mappings table that maps raw OTel
      attribute keys to canonical semantic concepts. Changes propagate to the
      backing ClickHouse dictionary within 1-2 minutes and affect all tenants.
  - name: server-info-v3
    description: Endpoints related to retrieving server information
  - name: sessions-v3
    description: v3 session APIs
  - name: team-roles-v3
  - name: team-v3
  - name: traces-v3
    description: v3 trace api for monitoring
  - name: fetch-sessions-v3
    description: v3 fetch sessions api for monitoring
  - name: user-access-key
    description: >
      CRUD operations for user API keys. All endpoints are user-scoped — each
      user can only operate on their own API keys. No one including Org admins
      have access to other users' API keys.
  - name: users-v3
  - name: version-compatibility-v3
  - name: webhooks
externalDocs:
  url: https://docs.fiddler.ai
  description: Find out more about Fiddler
paths:
  /v3/queries:
    post:
      tags:
        - queries-v3
      summary: API to fetch metrics used to plot monitoring charts
      description: API to fetch metrics used to plot monitoring charts
      operationId: getQueriesV3
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/MonitoringQueryRequest'
                - $ref: '#/components/schemas/LLMQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        oneOf:
                          - $ref: '#/components/schemas/MonitoringQueryResponse'
                          - $ref: '#/components/schemas/LLMMonitoringQueryResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    MonitoringQueryRequest:
      allOf:
        - type: object
          properties:
            project_id:
              description: Unique identifier of the project
              type: string
              format: uuid
          required:
            - project_id
        - $ref: '#/components/schemas/MonitoringQueryRequestObject'
    LLMQueryRequest:
      allOf:
        - type: object
          properties:
            project_id:
              description: Unique identifier of the project
              type: string
              format: uuid
          required:
            - project_id
        - $ref: '#/components/schemas/LLMQueryRequestObject'
    ApiResponse:
      type: object
      description: |
        Response object for standard API responses.
      properties:
        api_version:
          type: string
          default: '3.0'
          enum:
            - '2.0'
            - '3.0'
          description: |
            API version.
        kind:
          type: string
          default: NORMAL
          enum:
            - NORMAL
          description: |
            Type of response, indicating a normal response.
    MonitoringQueryResponse:
      type: object
      required:
        - organization
        - project
        - query_type
        - filters
      properties:
        organization:
          $ref: '#/components/schemas/OrganizationCompact'
        project:
          $ref: '#/components/schemas/ProjectCompact'
        time_comparison:
          description: Specifes the time period to comapre the data against.
          type: string
          enum:
            - Previous Day
            - Previous Week
            - Previous Month
            - Previous Quarter
            - Previous Year
            - null
          nullable: true
        query_type:
          $ref: '#/components/schemas/QueryType'
        filters:
          $ref: '#/components/schemas/QueryFilters'
        results:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MonitoringQueryResponseObject'
    LLMMonitoringQueryResponse:
      type: object
      required:
        - organization
        - project
        - query_type
        - time_filters
        - results
      properties:
        organization:
          $ref: '#/components/schemas/OrganizationCompact'
        project:
          $ref: '#/components/schemas/ProjectCompact'
        query_type:
          $ref: '#/components/schemas/LLMQueryType'
        time_filters:
          $ref: '#/components/schemas/LLMTimeFilters'
        results:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/LLMMonitoringQueryResponseObject'
    MonitoringQueryRequestObject:
      type: object
      title: Monitoring queries request object
      description: Monitoring queries request object
      properties:
        time_comparison:
          description: Specifes the time period to comapre the data against
          type: string
          enum:
            - Previous Day
            - Previous Week
            - Previous Month
            - Previous Quarter
            - Previous Year
        query_type:
          $ref: '#/components/schemas/QueryType'
        filters:
          $ref: '#/components/schemas/QueryFilters'
        queries:
          type: array
          items:
            $ref: '#/components/schemas/QueryMonitoringRequestFields'
    LLMQueryRequestObject:
      type: object
      title: LLM Monitoring queries request object
      description: LLM Monitoring queries request object
      properties:
        query_type:
          $ref: '#/components/schemas/LLMQueryType'
        time_filters:
          $ref: '#/components/schemas/LLMTimeFilters'
        queries:
          type: array
          items:
            $ref: '#/components/schemas/LLMQueryMonitoringRequestFields'
    OrganizationCompact:
      type: object
      title: OrganizationCompact
      description: >
        Compact version of an organization which can be included in the response
        of relevant APIs.
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: |
            Unique identifier of the organization.
        name:
          type: string
          description: |
            Name of the organization.
    ProjectCompact:
      type: object
      title: ProjectCompact
      description: >
        Compact version of a project which can be included in the response of
        relevant APIs.
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: |
            Unique identifier of the project.
        name:
          type: string
          description: |
            Name of the project.
        asset_type:
          type: string
          enum:
            - ML_MODEL
            - GEN_AI_APP
          description: |
            Type of assets the project can have.
    QueryType:
      type: string
      description: Specfies the query type to fetch the corresponding metrics
      enum:
        - MONITORING
        - EMBEDDING
        - ANALYTICS
    QueryFilters:
      type: object
      title: QueryFilter
      description: |
        Filters for querying data, including time, time zone, and bin size.
      required:
        - time_zone
        - bin_size
      properties:
        time_label:
          type: string
          enum:
            - yesterday
            - today
            - 7d
            - 30d
            - 90d
            - 6m
            - 12m
            - ytd
            - null
          nullable: true
          description: |
            Time label for filtering data within specific time ranges.
        time_range:
          type: object
          nullable: true
          properties:
            start_time:
              type: string
              format: date-time
              description: |
                Start time of the time range for querying data.
            end_time:
              type: string
              format: date-time
              description: |
                End time of the time range for querying data.
          required:
            - start_time
            - end_time
          description: |
            Custom time range for querying data.
        time_zone:
          type: string
          default: Etc/GMT
          description: |
            Time zone used for data filtering.
        bin_size:
          type: string
          enum:
            - Hour
            - Day
            - Week
            - Month
            - Quarter
          default: Hour
          description: |
            Bin size for grouping data in queries, defaulting to hourly bins.
    MonitoringQueryResponseObject:
      type: object
      required:
        - query_key
        - model
        - metric
        - viz_type
        - col_names
        - data
      properties:
        query_key:
          description: Unique identifier of the query.
          type: string
          format: uuid
        model:
          $ref: '#/components/schemas/ModelCompact'
        baseline:
          $ref: '#/components/schemas/BaselineCompact'
        segment:
          $ref: '#/components/schemas/SegmentCompact'
        metric:
          description: Metric key.
          type: string
        viz_type:
          description: Specifies the visualization Type for the UI.
          type: string
          enum:
            - line
            - bar
        columns:
          description: List of columns.
          type: array
          items:
            type: string
        col_names:
          description: List of column names.
          type: array
          uniqueItems: true
          items:
            type: string
        data:
          description: The metric response data.
          type: array
          items:
            type: array
            items:
              anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                  nullable: true
    LLMQueryType:
      type: string
      description: Specifies the chart type to fetch the corresponding metrics
      enum:
        - GEN_AI_MONITORING
        - GEN_AI_METRICS
    LLMTimeFilters:
      type: object
      title: LLM Time Filters
      description: >
        Filters for querying data, including time range, time zone, and bin
        size(Only for monitoring queries).
      oneOf:
        - required:
            - time_label
        - required:
            - time_range
      properties:
        time_label:
          type: string
          enum:
            - yesterday
            - today
            - 7d
            - 30d
            - 90d
            - 6m
            - 12m
            - ytd
            - null
          nullable: true
          description: |
            Time label for filtering data within specific time ranges.
        time_range:
          type: object
          nullable: true
          properties:
            start_time:
              type: string
              format: date-time
              description: |
                Start time of the time range for querying data.
            end_time:
              type: string
              format: date-time
              description: |
                End time of the time range for querying data.
          required:
            - start_time
            - end_time
          description: |
            Custom time range for querying data.
        time_zone:
          type: string
          default: Etc/GMT
          description: |
            Time zone used for data filtering.
        bin_size:
          type: string
          enum:
            - Hour
            - Day
            - Week
            - Month
          default: Hour
          description: >
            Bin size for grouping data in monitoring queries, defaulting to
            hourly bins.
        time_comparison:
          description: Specifes the time period to comapre the current data against
          type: string
          enum:
            - Previous Day
            - Previous Week
            - Previous Month
            - Previous Quarter
            - Previous Year
    LLMMonitoringQueryResponseObject:
      type: object
      required:
        - query_key
        - query_type
        - application
        - viz_type
        - data
        - chart_col_names
        - metric_source
        - metric_name
        - aggregation
      properties:
        query_type:
          $ref: '#/components/schemas/LLMQueryType'
        query_key:
          description: Unique identifier of the query.
          type: string
          format: uuid
        application:
          $ref: '#/components/schemas/ChartApplicationCompact'
        chart_col_names:
          description: List of chart column names.
          type: array
          uniqueItems: true
          items:
            type: string
        viz_type:
          description: Specifies the visualization Type for the UI.
          type: string
          enum:
            - line
            - bar
        data:
          description: The metric response data.
          type: array
          items:
            type: array
            items:
              anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                  nullable: true
        metric_source:
          $ref: '#/components/schemas/GenAIMetricSourceEnum'
        metric_name:
          $ref: '#/components/schemas/GenAIMetricName'
        aggregation:
          $ref: '#/components/schemas/GenAIAggregationEnum'
        metric_params:
          $ref: '#/components/schemas/GenAIMetricParams'
        timestamp_mode:
          type: string
          nullable: true
          enum:
            - event_time
            - processing_time
          description: >-
            The time axis used for this query. Echoes back the timestamp_mode
            from the request.
    ErrorResponse:
      type: object
      description: |
        Response object for errors returned by the API.
      properties:
        api_version:
          type: string
          default: '3.0'
          enum:
            - '2.0'
            - '3.0'
          description: |
            API version of the response.
        kind:
          type: string
          default: ERROR
          enum:
            - ERROR
          description: |
            Type of response, usually indicating an error.
        error:
          type: object
          properties:
            code:
              type: integer
              format: int32
              description: >
                Represents the code for this error, typically an HTTP response
                code.
              default: 400
              enum:
                - 400
                - 403
                - 404
                - 500
            message:
              type: string
              description: >
                A human-readable message providing more details about the error.
                If there are multiple errors, it will be the message for the
                first error.
              example: Resource Not Found
            errors:
              type: array
              description: >
                Container for additional information regarding the error,
                especially for multiple errors.
              items:
                type: object
                properties:
                  reason:
                    type: string
                    description: >
                      Unique identifier for this error, different from the error
                      code.
                    example: ResourceNotFoundException
                  message:
                    type: string
                    description: >
                      A human-readable message providing more details about the
                      error. If there is only one error, this field will match
                      error.message.
                    example: Resource Not Found
                  help:
                    type: string
                    description: >
                      Link to support or documentation providing more
                      information on the error.
    QueryMonitoringRequestFields:
      type: object
      title: Monitoring query request fields
      description: Monitoring query request fields
      required:
        - query_key
        - model_id
        - metric
        - columns
      properties:
        query_key:
          description: Unique identifier of the query.
          type: string
          format: uuid
        model_id:
          description: Unique identifier of the model.
          type: string
          format: uuid
        baseline_id:
          description: Unique identifier of the baseline.
          type: string
          format: uuid
        metric:
          description: Metric key.
          type: string
        columns:
          description: List of column names.
          type: array
          items:
            type: string
        categories:
          description: List of categories.
          type: array
          items:
            type: string
        segment_id:
          description: Unique identifier of the baseline.
          type: string
          format: uuid
        segment:
          $ref: '#/components/schemas/SegmentCompact'
        viz_type:
          description: Specifies the visualization Type for the UI.
          type: string
          enum:
            - line
            - bar
    LLMQueryMonitoringRequestFields:
      type: object
      title: Monitoring query request fields
      description: Monitoring query request fields
      required:
        - query_key
        - query_scope
        - query_type
        - application_id
        - viz_type
        - metric_source
        - metric_name
      properties:
        query_type:
          $ref: '#/components/schemas/LLMQueryType'
        query_key:
          description: Unique identifier of the query.
          type: string
          format: uuid
        query_scope:
          description: Query scope
          type: string
          enum:
            - SPAN
            - SESSION
        application_id:
          description: Unique identifier of the application
          type: string
          format: uuid
        filters:
          $ref: '#/components/schemas/LLMQueryFilters'
        viz_type:
          description: Specifies the visualization Type for the UI.
          type: string
          enum:
            - line
            - bar
        metric_source:
          $ref: '#/components/schemas/GenAIMetricSourceEnum'
        metric_name:
          $ref: '#/components/schemas/GenAIMetricName'
        aggregation:
          $ref: '#/components/schemas/GenAIAggregationEnum'
        metric_params:
          $ref: '#/components/schemas/GenAIMetricParams'
        timestamp_mode:
          type: string
          nullable: true
          enum:
            - event_time
            - processing_time
          description: >-
            Controls which time axis is used for query binning and filtering.
            Use processing_time for evaluator alert previews to match actual
            alert evaluation behavior. Defaults to event_time when not provided.
    ModelCompact:
      type: object
      title: ModelCompact
      description: >
        Compact version of a model which can be included in the response of
        relevant APIs.
      required:
        - id
        - name
        - version
      properties:
        id:
          type: string
          format: uuid
          description: |
            Unique identifier for the model.
        name:
          type: string
          description: |
            Name of the model.
        version:
          type: string
          description: |
            Version of the model.
    BaselineCompact:
      type: object
      title: BaselineCompact
      description: >
        Compact version of a baseline which can be included in the response of
        relevant APIs.
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: |
            Unique identifier of the baseline.
        name:
          type: string
          description: |
            Name of the baseline.
    SegmentCompact:
      type: object
      title: SegmentCompact
      description: Compact version of segment for v3
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the saved segment
        definition:
          type: string
          description: FQL definition of the applied segment
    ChartApplicationCompact:
      type: object
      title: Chart ApplicationCompact
      description: Compact version of an application for chart v3
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    GenAIMetricSourceEnum:
      type: string
      description: Source of the metric data
      enum:
        - raw_data
        - attribute
        - evaluator
        - custom
    GenAIMetricName:
      type: string
      description: >
        Name of the metric. For core metrics this is one of traffic,
        token_count, attribute, latency, or custom_metric. For evaluator metrics
        this is the enrichment name (e.g., topic_classification, sentiment).
    GenAIAggregationEnum:
      type: string
      description: Supported aggregation types for GenAI metrics
      enum:
        - sum
        - average
        - p50
        - p75
        - p90
        - p95
        - p99
        - count
    GenAIMetricParams:
      type: object
      description: >-
        Additional parameters for the metric. Which fields are required depends
        on metric_source.
      properties:
        attribute_name:
          type: string
          description: Name of the attribute (required for attribute metrics)
        attribute_values:
          type: array
          items:
            type: string
          description: >-
            List of attribute values (required for attribute metrics with count
            aggregation)
        rule_name:
          type: string
          description: Name of the evaluator rule (required for evaluator metrics)
        output_name:
          type: string
          description: Name of the evaluator output (required for evaluator metrics)
        output_values:
          type: array
          items:
            type: string
          description: >-
            List of evaluator output values (required for evaluator metrics with
            count aggregation)
        custom_metric_id:
          type: string
          format: uuid
          description: UUID of the custom metric to execute (required for custom metrics)
    LLMQueryFilters:
      type: object
      title: LLM Query Filters
      description: Filters for querying data
      properties:
        agents:
          type: array
          items:
            type: string
          description: List of agent names to filter by
          default: []
        span_groups:
          type: array
          items:
            type: string
          description: List of span groups to filter by
          default: []
        span_types:
          type: array
          description: List of span types to filter by
          items:
            $ref: '#/components/schemas/SpanType'
          default: []
        evaluator_rules:
          type: array
          items:
            $ref: '#/components/schemas/EvaluatorFilter'
          default: []
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/AttributeFilter'
          default: []
        token_counts:
          type: array
          items:
            $ref: '#/components/schemas/TokenCountFilter'
          default: []
        latency:
          type: array
          items:
            $ref: '#/components/schemas/LatencyFilter'
          default: []
    SpanType:
      type: string
      enum:
        - llm
        - tool
        - agent
        - chain
    EvaluatorFilter:
      type: object
      title: Rule Evaluator Filters
      description: Filters for rule evaluators
      required:
        - name
        - output_name
      properties:
        name:
          type: string
        output_name:
          type: string
        min:
          type: number
          description: Filter values greater or equal than this minimal value
        max:
          type: number
          description: Filter values lower or equal than this maximal value
        categories:
          type: array
          description: Filter values in those categories
          items:
            anyOf:
              - type: string
              - type: boolean
    AttributeFilter:
      type: object
      title: Attribute Filters
      description: Filters for attributes(span and session)
      required:
        - name
      properties:
        name:
          type: string
        min:
          type: number
          description: Filter values greater or equal than this minimal value
        max:
          type: number
          description: Filter values lower or equal than this maximal value
        categories:
          type: array
          description: Filter values in those categories(when attribute is categorical)
          items:
            anyOf:
              - type: string
              - type: number
    TokenCountFilter:
      type: object
      title: Token Count Filters
      description: Filters for token counts
      required:
        - name
      properties:
        name:
          type: string
        min:
          type: number
          description: Filter values greater or equal than this minimal value
        max:
          type: number
          description: Filter values lower or equal than this maximal value
    LatencyFilter:
      type: object
      title: Latency Filters
      description: Filters for latency
      required:
        - name
        - unit
      properties:
        name:
          type: string
        min:
          type: number
          description: Filter values greater or equal than this minimal value
        max:
          type: number
          description: Filter values lower or equal than this maximal value
        unit:
          $ref: '#/components/schemas/TimeUnit'
    TimeUnit:
      type: string
      enum:
        - microseconds
        - milliseconds
        - seconds
        - minutes
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '404':
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````