SpansBySpanMetricsRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/scale-ai/json-schema/scale-ai-spans-by-span-metrics-request-schema.json",
  "title": "SpansBySpanMetricsRequest",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/scale-ai-sgp-v5-openapi.yml#/components/schemas/SpansBySpanMetricsRequest",
  "properties": {
    "parents_only": {
      "title": "Parents Only",
      "description": "Only fetch spans that are the top-level (ie. have no parent_id)",
      "type": "boolean"
    },
    "span_ids": {
      "title": "Span Ids",
      "description": "Filter by span IDs",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "trace_ids": {
      "title": "Trace Ids",
      "description": "Filter by trace IDs. The combined count of trace_ids, span_ids, excluded_span_ids, excluded_trace_ids, and parent_ids may not exceed 10000. A request over that returns 422.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "excluded_span_ids": {
      "title": "Excluded Span Ids",
      "description": "List of span IDs to exclude from results",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "excluded_trace_ids": {
      "title": "Excluded Trace Ids",
      "description": "List of trace IDs to exclude from results",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "group_id": {
      "title": "Group Id",
      "description": "Filter by group ID",
      "type": "string"
    },
    "parent_ids": {
      "title": "Parent Ids",
      "description": "Filter to the direct children of any of these parent span IDs",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "names": {
      "title": "Names",
      "description": "Filter by trace/span name",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "statuses": {
      "title": "Statuses",
      "description": "Filter on span status",
      "items": {
        "$ref": "#/$defs/ApplicationOperationStatus"
      },
      "type": "array"
    },
    "types": {
      "title": "Types",
      "items": {
        "$ref": "#/$defs/ApplicationOperationType"
      },
      "type": "array"
    },
    "search_texts": {
      "title": "Search Texts",
      "description": "Case-insensitive substring search across span name, input, output, and metadata (no tokenization or stemming). Multiple terms are ANDed, and UUID-shaped terms match trace IDs instead. Substring means mid-word fragments match, while an inflected form such as a plural matches only where it appears literally. A span must match every non-UUID term, and each term may match any of the searched fields. UUID matches are ORed onto the text match. Each term must be at least 2 characters. For exact trace ID lookup, use the `trace_ids` filter. Accounts still served by the legacy trace store match differently until migrated: terms match as stemmed whole words rather than substrings, only input and output are searched, the 2-character minimum is not enforced, and characters like `:`, `|`, or `!` inside a term may be interpreted as query operators or cause an error.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "extra_metadata": {
      "title": "Extra Metadata",
      "description": "Filter on custom metadata key-value pairs",
      "additionalProperties": true,
      "type": "object"
    },
    "application_variant_ids": {
      "title": "Application Variant Ids",
      "description": "Filter by application variant IDs",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "assessment_types": {
      "title": "Assessment Types",
      "description": "Filter to spans that have at least one assessment of these types",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "acp_types": {
      "title": "Acp Types",
      "description": "Filter by ACP types",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "agentex_agent_names": {
      "title": "Agentex Agent Names",
      "description": "Filter by Agentex agent names",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "agentex_agent_ids": {
      "title": "Agentex Agent Ids",
      "description": "Filter by Agentex agent IDs",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "min_duration_ms": {
      "title": "Min Duration Ms",
      "description": "Minimum span duration in milliseconds (inclusive). An in-flight span with no end time has no known duration and is treated as unbounded, so it matches every minimum.",
      "type": "integer"
    },
    "max_duration_ms": {
      "title": "Max Duration Ms",
      "description": "Maximum span duration in milliseconds (inclusive). An in-flight span with no end time has no known duration and is treated as unbounded, so it never falls within a maximum and is excluded.",
      "type": "integer"
    },
    "limit": {
      "type": "integer",
      "title": "Limit",
      "description": "Max number of span groups to return",
      "default": 100
    },
    "offset": {
      "type": "integer",
      "title": "Offset",
      "description": "Offset for pagination of span groups",
      "default": 0
    },
    "sort_by": {
      "type": "string",
      "title": "Sort By",
      "description": "Field to sort by: 'total_ms', 'max_ms', 'avg_ms', or 'count'",
      "default": "total_ms"
    }
  },
  "type": "object",
  "$defs": {
    "ApplicationOperationStatus": {
      "type": "string",
      "enum": [
        "SUCCESS",
        "ERROR",
        "CANCELED"
      ],
      "title": "ApplicationOperationStatus"
    },
    "ApplicationOperationType": {
      "type": "string",
      "enum": [
        "TEXT_INPUT",
        "TEXT_OUTPUT",
        "COMPLETION_INPUT",
        "COMPLETION",
        "KB_RETRIEVAL",
        "KB_INPUT",
        "RERANKING",
        "EXTERNAL_ENDPOINT",
        "PROMPT_ENGINEERING",
        "DOCUMENT_INPUT",
        "MAP_REDUCE",
        "DOCUMENT_SEARCH",
        "DOCUMENT_PROMPT",
        "CUSTOM",
        "CODE_EXECUTION",
        "DATA_MANIPULATION",
        "EVALUATION",
        "FILE_RETRIEVAL",
        "KB_ADD_CHUNK",
        "KB_MANAGEMENT",
        "GUARDRAIL",
        "OUTPUT_GUARDRAIL",
        "TRACER",
        "AGENT_TRACER",
        "AGENT_WORKFLOW",
        "STANDALONE"
      ],
      "title": "ApplicationOperationType"
    }
  }
}