> ## Documentation Index > Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt > Use this file to discover all available pages before exploring further. # Get span metrics grouped by name > Compute duration metrics aggregated by span name across the filtered set. Returns one row per distinct span name plus overall totals (unique traces and total spans considered). Each row includes occurrence count, min/avg/max and p50/p90/p95/p99 durations, summed duration, share of total time, and average occurrences per trace — use this to profile which span names dominate latency. Results can be sorted (``sort_by``, default ``total_ms``) and paginated with ``limit``/``offset``, and are narrowed to traces the caller is authorized to read. A reversed time window (``from_ts`` after ``to_ts``) is rejected with 422. ## OpenAPI ````yaml https://api.sgp.scale.com/openapi-versions/v5/openapi.json post /v5/spans/metrics/by-span openapi: 3.1.0 info: title: EGP API V5 description: >- This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs. contact: name: Scale Generative AI Platform url: https://scale.com/genai-platform version: 0.1.0 servers: - url: https://api.egp.scale.com security: [] paths: /v5/spans/metrics/by-span: post: tags: - Spans summary: Get span metrics grouped by name description: >- Compute duration metrics aggregated by span name across the filtered set. Returns one row per distinct span name plus overall totals (unique traces and total spans considered). Each row includes occurrence count, min/avg/max and p50/p90/p95/p99 durations, summed duration, share of total time, and average occurrences per trace — use this to profile which span names dominate latency. Results can be sorted (``sort_by``, default ``total_ms``) and paginated with ``limit``/``offset``, and are narrowed to traces the caller is authorized to read. A reversed time window (``from_ts`` after ``to_ts``) is rejected with 422. operationId: POST-V5-/v5/spans/metrics/by-span parameters: - name: from_ts in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: The starting (oldest) timestamp in ISO format. title: From Ts description: The starting (oldest) timestamp in ISO format. - name: to_ts in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: The ending (most recent) timestamp in ISO format. title: To Ts description: The ending (most recent) timestamp in ISO format. - name: x-selected-account-id in: header required: false schema: anyOf: - type: string - type: 'null' title: Account ID Header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SpansBySpanMetricsRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SpansBySpanMetricsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] 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: '#/components/schemas/ApplicationOperationStatus' type: array types: title: Types items: $ref: '#/components/schemas/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 title: SpansBySpanMetricsRequest SpansBySpanMetricsResponse: properties: items: items: $ref: '#/components/schemas/SpansBySpanMetricsItem' type: array title: Items totals: $ref: '#/components/schemas/SpansBySpanMetricsTotals' type: object required: - items - totals title: SpansBySpanMetricsResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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 SpansBySpanMetricsItem: properties: span_name: type: string title: Span Name description: The span name being aggregated count: type: integer title: Count description: Total occurrences across the filtered set min_ms: type: number title: Min Ms description: Minimum duration in milliseconds avg_ms: type: number title: Avg Ms description: Average duration in milliseconds p50_ms: type: number title: P50 Ms description: Median duration in milliseconds p90_ms: type: number title: P90 Ms description: 90th percentile duration in milliseconds p95_ms: type: number title: P95 Ms description: 95th percentile duration in milliseconds p99_ms: type: number title: P99 Ms description: 99th percentile duration in milliseconds max_ms: type: number title: Max Ms description: Maximum duration in milliseconds total_ms: type: number title: Total Ms description: Sum of durations across all occurrences total_time_pct: type: number title: Total Time Pct description: Percent of total time across all spans avg_per_trace: type: number title: Avg Per Trace description: Average occurrences per trace type: object required: - span_name - count - min_ms - avg_ms - p50_ms - p90_ms - p95_ms - p99_ms - max_ms - total_ms - total_time_pct - avg_per_trace title: SpansBySpanMetricsItem SpansBySpanMetricsTotals: properties: total_traces: type: integer title: Total Traces description: Number of unique traces in result total_spans: type: integer title: Total Spans description: Total number of spans considered type: object required: - total_traces - total_spans title: SpansBySpanMetricsTotals ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: title: Error Type type: string input: title: Input ctx: type: object title: Context additionalProperties: true type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key ````