{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/llmpulse-ai/json-schema/llmpulse-ai-ai-model-insights-summary-response-schema.json",
  "title": "AiModelInsightsSummaryResponse",
  "description": "One entry per AI model the account has enabled or that answered in the window, in the in-app column order: the models list, which every per-model list and map in summary follows. A share, net sentiment or market share value with nothing behind it is null, because 0 is a real value; counts, totals and weighted visibility scores stay 0.",
  "x-generated": "2026-11-17",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/llmpulse-ai-openapi.json#/components/schemas/AiModelInsightsSummaryResponse",
  "type": "object",
  "properties": {
    "project_id": {
      "type": "integer"
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "filters": {
      "$ref": "#/$defs/AiModelInsightsFiltersEcho"
    },
    "models": {
      "type": "array",
      "description": "The AI models the account has enabled or that answered in the window, in the in-app column order",
      "items": {
        "$ref": "#/$defs/AiModelInsightsModel"
      }
    },
    "summary": {
      "type": "object",
      "properties": {
        "mentions_by_model": {
          "type": "object",
          "properties": {
            "total_mentions": {
              "type": "integer",
              "description": "Brand mentions across the models"
            },
            "models": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/AiModelMentionsRow"
              }
            }
          }
        },
        "citations_by_model": {
          "type": "object",
          "properties": {
            "total_citations": {
              "type": "integer",
              "description": "Citations of the brand's URLs across the models"
            },
            "models": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/AiModelCitationsRow"
              }
            }
          }
        },
        "brand_net_sentiment_by_model": {
          "type": "object",
          "properties": {
            "total_sentiments": {
              "type": "integer",
              "description": "Brand sentiment verdicts across the models"
            },
            "models": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/AiModelSentimentRow"
              }
            }
          }
        },
        "weighted_visibility_by_model": {
          "type": "object",
          "properties": {
            "total_weighted_visibility_score": {
              "type": "number",
              "description": "The brand's AI Visibility Score across the enabled models, its points there divided by the tracking runs with answers in any of them (the Overview's number for the same filters; a model that answered while disabled keeps its row but stays out of it); 0 when it has none"
            },
            "models": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/AiModelWeightedVisibilityRow"
              }
            }
          }
        },
        "mentions_market_share": {
          "$ref": "#/$defs/AiModelRateMatrix"
        },
        "citations_market_share": {
          "$ref": "#/$defs/AiModelRateMatrix"
        },
        "sentiment_market_share": {
          "type": "object",
          "properties": {
            "actors": {
              "type": "array",
              "description": "The project and each competitor with a sentiment verdict in the window (only the competitors given in competitors, when it is given), by total_sentiments descending",
              "items": {
                "$ref": "#/$defs/AiModelSentimentMatrixActor"
              }
            }
          }
        },
        "weighted_visibility_market_share": {
          "type": "object",
          "properties": {
            "actors": {
              "type": "array",
              "description": "The project and each competitor with an AI Visibility Score in the window, 0 included (only the competitors given in competitors, when it is given), by total_weighted_visibility_score descending",
              "items": {
                "$ref": "#/$defs/AiModelWeightedVisibilityMatrixActor"
              }
            }
          }
        }
      }
    },
    "request_id": {
      "type": "string"
    }
  },
  "$defs": {
    "AiModelCitationsRow": {
      "allOf": [
        {
          "$ref": "#/$defs/AiModelInsightsModel"
        },
        {
          "type": "object",
          "properties": {
            "citations_count": {
              "type": "integer",
              "description": "Citations of the brand's URLs in the model's answers; 0 when it has none"
            },
            "share_of_total": {
              "type": [
                "number",
                "null"
              ],
              "description": "The model's percentage (0-100) of total_citations; null when total_citations is 0"
            }
          }
        }
      ]
    },
    "AiModelInsightsFiltersEcho": {
      "type": "object",
      "description": "The filters the summary was computed with, as the server resolved them. A filter that was not given is left out, except granularity and competitors.",
      "properties": {
        "from": {
          "type": "string",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "format": "date-time"
        },
        "granularity": {
          "type": "string",
          "description": "day, week or month; day when not given"
        },
        "country_code": {
          "type": "string",
          "description": "Comma-separated country codes"
        },
        "language_code": {
          "type": "string",
          "description": "Comma-separated language codes"
        },
        "collection_id": {
          "type": "string",
          "description": "Comma-separated collection ids"
        },
        "prompt_type": {
          "type": "string",
          "description": "Comma-separated prompt types"
        },
        "brand_kind": {
          "type": "string"
        },
        "competitors": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Competitor ids from the competitors parameter; empty when it was not given"
        }
      }
    },
    "AiModelInsightsModel": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string",
          "description": "AI model key, as /dimensions/models lists it"
        },
        "label": {
          "type": "string",
          "description": "Display name of the model"
        },
        "color": {
          "type": "string",
          "description": "Hex color the app charts the model with"
        }
      }
    },
    "AiModelMentionsRow": {
      "allOf": [
        {
          "$ref": "#/$defs/AiModelInsightsModel"
        },
        {
          "type": "object",
          "properties": {
            "mentions_count": {
              "type": "integer",
              "description": "Brand mentions in the model's answers; 0 when it has none"
            },
            "share_of_total": {
              "type": [
                "number",
                "null"
              ],
              "description": "The model's percentage (0-100) of total_mentions; null when total_mentions is 0"
            }
          }
        }
      ]
    },
    "AiModelRateCell": {
      "type": "object",
      "properties": {
        "value": {
          "type": [
            "number",
            "null"
          ],
          "description": "numerator as a percentage (0-100) of denominator; null when the model has no answers in the window"
        },
        "numerator": {
          "type": "integer",
          "description": "Mentions of the actor (or answers citing it) in the model's answers"
        },
        "denominator": {
          "type": "integer",
          "description": "Answers of the model in the window"
        }
      }
    },
    "AiModelRateMatrix": {
      "type": "object",
      "description": "Each actor's rate within each model: mentions of the actor (mentions_market_share), or answers citing it (citations_market_share), per answer of the model. Rates are independent, so the actors of a model can add up to more or less than 100.",
      "properties": {
        "denominators_by_model": {
          "type": "object",
          "description": "Answers of each model in the window, keyed by model",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "actors": {
          "type": "array",
          "description": "The project and each competitor with a mention (or citation) in the window (only the competitors given in competitors, when it is given), by total descending",
          "items": {
            "$ref": "#/$defs/AiModelRateMatrixActor"
          }
        }
      }
    },
    "AiModelRateMatrixActor": {
      "type": "object",
      "description": "An actor (the standard actor shape) with one rate cell per model",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "project",
            "competitor"
          ]
        },
        "id": {
          "type": "integer",
          "description": "Project id, or competitor id"
        },
        "competitor_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Null for the project, the competitor id otherwise"
        },
        "name": {
          "type": "string"
        },
        "domain": {
          "type": [
            "string",
            "null"
          ],
          "description": "Bare (scheme-less) domain. Null for the project actor when the project has no URL."
        },
        "total": {
          "type": "integer",
          "description": "The actor's numerators summed over the models"
        },
        "models": {
          "type": "object",
          "description": "One cell per model, keyed by model",
          "additionalProperties": {
            "$ref": "#/$defs/AiModelRateCell"
          }
        }
      }
    },
    "AiModelSentimentCell": {
      "type": "object",
      "properties": {
        "value": {
          "type": [
            "number",
            "null"
          ],
          "description": "The actor's net sentiment in the model, positive_count minus negative_count as a percentage (-100 to 100) of total_sentiments; null when total_sentiments is 0"
        },
        "total_sentiments": {
          "type": "integer",
          "description": "The actor's sentiment verdicts in the model's answers"
        },
        "positive_count": {
          "type": "integer",
          "description": "Positive and very positive verdicts"
        },
        "negative_count": {
          "type": "integer",
          "description": "Negative and very negative verdicts"
        }
      }
    },
    "AiModelSentimentMatrixActor": {
      "type": "object",
      "description": "An actor (the standard actor shape) with one net sentiment cell per model",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "project",
            "competitor"
          ]
        },
        "id": {
          "type": "integer",
          "description": "Project id, or competitor id"
        },
        "competitor_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Null for the project, the competitor id otherwise"
        },
        "name": {
          "type": "string"
        },
        "domain": {
          "type": [
            "string",
            "null"
          ],
          "description": "Bare (scheme-less) domain. Null for the project actor when the project has no URL."
        },
        "total_sentiments": {
          "type": "integer",
          "description": "The actor's sentiment verdicts summed over the models"
        },
        "models": {
          "type": "object",
          "description": "One cell per model, keyed by model",
          "additionalProperties": {
            "$ref": "#/$defs/AiModelSentimentCell"
          }
        }
      }
    },
    "AiModelSentimentRow": {
      "allOf": [
        {
          "$ref": "#/$defs/AiModelInsightsModel"
        },
        {
          "type": "object",
          "properties": {
            "sentiments_count": {
              "type": "integer",
              "description": "Brand sentiment verdicts in the model's answers"
            },
            "positive_count": {
              "type": "integer",
              "description": "Positive and very positive verdicts"
            },
            "negative_count": {
              "type": "integer",
              "description": "Negative and very negative verdicts"
            },
            "net_sentiment": {
              "type": [
                "number",
                "null"
              ],
              "description": "positive_count minus negative_count as a percentage (-100 to 100) of sentiments_count, neutral verdicts counted in the base; null when sentiments_count is 0"
            }
          }
        }
      ]
    },
    "AiModelWeightedVisibilityCell": {
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "description": "The actor's AI Visibility Score in the model, its points there divided by the project's tracking runs with answers in that model; 0 when it has none"
        }
      }
    },
    "AiModelWeightedVisibilityMatrixActor": {
      "type": "object",
      "description": "An actor (the standard actor shape) with one AI Visibility Score cell per model",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "project",
            "competitor"
          ]
        },
        "id": {
          "type": "integer",
          "description": "Project id, or competitor id"
        },
        "competitor_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Null for the project, the competitor id otherwise"
        },
        "name": {
          "type": "string"
        },
        "domain": {
          "type": [
            "string",
            "null"
          ],
          "description": "Bare (scheme-less) domain. Null for the project actor when the project has no URL."
        },
        "total_weighted_visibility_score": {
          "type": "number",
          "description": "The actor's AI Visibility Score across the enabled models, its points there divided by the project's tracking runs with answers in them, so actors compare"
        },
        "models": {
          "type": "object",
          "description": "One cell per model, keyed by model",
          "additionalProperties": {
            "$ref": "#/$defs/AiModelWeightedVisibilityCell"
          }
        }
      }
    },
    "AiModelWeightedVisibilityRow": {
      "allOf": [
        {
          "$ref": "#/$defs/AiModelInsightsModel"
        },
        {
          "type": "object",
          "properties": {
            "weighted_visibility_score": {
              "type": "number",
              "description": "The brand's AI Visibility Score in the model, its points there divided by the days the model answered; 0 when it has none"
            },
            "share_of_total": {
              "type": [
                "number",
                "null"
              ],
              "description": "The model's percentage (0-100) of the brand's AI Visibility Score points; null when the brand has none"
            }
          }
        }
      ]
    }
  }
}