SpansExportRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/scale-ai/json-schema/scale-ai-spans-export-request-schema.json",
  "title": "SpansExportRequest",
  "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/SpansExportRequest",
  "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"
    },
    "export_method": {
      "$ref": "#/$defs/ExportMethod",
      "description": "The method for exporting spans. `signed_url` returns a pre-signed URL, while `direct` returns the raw content.",
      "default": "direct"
    },
    "export_format": {
      "$ref": "#/$defs/SpanExportFormat",
      "description": "The format of the exported spans. `json` is a single JSON array and `jsonl` one JSON object per span per line (both flat); `trace_jsonl` is trace-grouped, one line per trace `{trace_id, spans:[...]}` with the trace's spans in pre-order DFS (reconstruct the tree from `parent_id`); `trace_jsonl` cannot be combined with `include_assessments`. `trace_jsonl` also excludes spans with an empty `trace_id` (they cannot be grouped), so its row count may be lower than `jsonl`'s, and any single trace exceeding the internal size cap is emitted truncated with `\"truncated\": true`.",
      "default": "json"
    },
    "with_children": {
      "type": "boolean",
      "title": "With Children",
      "description": "Whether to include child spans in the export. If true, all spans related to the trace will be included.",
      "default": false
    },
    "include_assessments": {
      "type": "boolean",
      "title": "Include Assessments",
      "description": "If true, include span assessments inline in the export under each span's 'assessments' field.",
      "default": false
    }
  },
  "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"
    },
    "ExportMethod": {
      "type": "string",
      "enum": [
        "signed_url",
        "direct"
      ],
      "title": "ExportMethod"
    },
    "SpanExportFormat": {
      "type": "string",
      "enum": [
        "json",
        "jsonl",
        "csv",
        "trace_jsonl"
      ],
      "title": "SpanExportFormat"
    }
  }
}