{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/llmpulse-ai/json-schema/llmpulse-ai-sov-response-schema.json",
  "title": "SovResponse",
  "x-generated": "2026-11-17",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/llmpulse-ai-openapi.json#/components/schemas/SovResponse",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "integer"
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "granularity": {
      "type": "string",
      "description": "day, week or month"
    },
    "filters": {
      "$ref": "#/$defs/MetricsFiltersEcho"
    },
    "periods": {
      "type": "array",
      "description": "Per-bucket sample size and completeness: mentions is the total the shares were computed on (1-3 mentions produce the 100/50/33.33 low-sample patterns); partial marks buckets still collecting data or clipped by the requested window; confidence and margin_of_error read the sample size.",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "mentions": {
            "type": "integer"
          },
          "partial": {
            "type": "boolean"
          },
          "confidence": {
            "type": "string",
            "description": "How far the shares of this period can be trusted, from its mentions: none (0), low (under 30), medium (under 100) or high (100 or more)."
          },
          "margin_of_error": {
            "type": [
              "number",
              "null"
            ],
            "description": "Worst-case 95% margin of a share in percentage points, 98 / sqrt(mentions); mentions within one answer are not independent, so the real margin is at least this wide. null with no mentions."
          }
        }
      }
    },
    "sample": {
      "type": [
        "object",
        "null"
      ],
      "description": "The period the current shares were computed on (the last one with mentions), same shape as a periods item; null when the window has no mentions.",
      "properties": {
        "date": {
          "type": "string",
          "format": "date"
        },
        "mentions": {
          "type": "integer"
        },
        "partial": {
          "type": "boolean"
        },
        "confidence": {
          "type": "string"
        },
        "margin_of_error": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "over_time": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "actor": {
            "$ref": "#/$defs/Actor"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/TimeseriesPoint"
            }
          }
        }
      }
    },
    "current": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "actor": {
            "$ref": "#/$defs/Actor"
          },
          "share": {
            "type": "number"
          },
          "previous_share": {
            "type": [
              "number",
              "null"
            ],
            "description": "The actor's share in the last complete bucket before the current one; null without complete history."
          },
          "avg_share": {
            "type": [
              "number",
              "null"
            ],
            "description": "Mean share across complete buckets with data (partial buckets excluded); null without complete history."
          }
        }
      }
    },
    "breakdown": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "actor": {
            "$ref": "#/$defs/Actor"
          },
          "share": {
            "type": "number"
          },
          "others": {
            "type": "boolean"
          }
        }
      }
    },
    "others": {
      "type": "array",
      "description": "Actors ranked fifth and below, folded into the Others share of breakdown",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "actor": {
            "$ref": "#/$defs/Actor"
          },
          "share": {
            "type": "number"
          }
        }
      }
    },
    "request_id": {
      "type": "string"
    }
  },
  "$defs": {
    "Actor": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "project",
            "competitor"
          ]
        },
        "id": {
          "type": "integer"
        },
        "competitor_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "name": {
          "type": "string"
        },
        "domain": {
          "type": [
            "string",
            "null"
          ],
          "description": "Bare (scheme-less) domain. Null for the project actor when the project has no URL."
        }
      }
    },
    "MetricsFiltersEcho": {
      "type": "object",
      "description": "The filters the response was computed with, as the server resolved them. Each endpoint echoes only the keys it reads; a filter that was not given comes back null (or an empty list).",
      "properties": {
        "metrics": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Requested metrics after alias resolution (mention_rate is echoed as visibility)"
        },
        "granularity": {
          "type": "string",
          "description": "day, week or month"
        },
        "model": {
          "type": [
            "string",
            "null"
          ],
          "description": "The model filter, or null when absent or not enabled for the account"
        },
        "collection_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "The collection_id parameter as sent (one id or a comma-separated list)"
        },
        "collection_ids": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer"
          }
        },
        "domains": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "country_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Comma-separated country codes"
        },
        "language_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Comma-separated language codes"
        },
        "prompt": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The prompt id filter"
        },
        "prompt_type": {
          "type": [
            "string",
            "null"
          ],
          "description": "Comma-separated prompt types"
        },
        "brand_kind": {
          "type": [
            "string",
            "null"
          ]
        },
        "competitors": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Competitor ids from the competitors parameter; empty when it was not given"
        },
        "include_project": {
          "type": "boolean"
        },
        "query": {
          "type": "string",
          "description": "Only present when a query filter was given"
        }
      }
    },
    "TimeseriesPoint": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "Calendar day in Europe/Madrid (YYYY-MM-DD). With granularity week or month it is the first day of the bucket (the Monday, or the 1st of the month)."
        },
        "value": {
          "type": [
            "number",
            "null"
          ],
          "description": "Null when the metric has no value for the bucket, e.g. a rate, position or sentiment metric on a day without answers."
        }
      }
    }
  }
}