{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/arcmira/main/json-schema/arcmira-mention-counts-response-schema.json",
  "title": "MentionCountsResponse",
  "x-generated": "2026-10-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/arcmira-v1-openapi.json#/components/schemas/MentionCountsResponse",
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "mentions",
        "appearances",
        "both"
      ],
      "description": "The mode applied."
    },
    "window": {
      "$ref": "#/$defs/PublicationWindow"
    },
    "channel_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The channel ids counted."
    },
    "video_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The video ids the count was scoped to. Empty when it was not."
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entity_id": {
            "type": "string",
            "description": "Public entity id (\"ent_{n}\")."
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "page": {
            "type": [
              "string",
              "null"
            ],
            "description": "The entity's page on arcmira.com, absolute. Link the name to it when you write the entity into an answer. Null for a type the site has no page for."
          },
          "appearances_page": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a person, the list of their appearances on arcmira.com (their page opens on it). Null for every other type."
          },
          "mentions_page": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a person, the list of mentions of them on arcmira.com, page/mentions. Null for every other type: their page is the mentions list already."
          },
          "slug": {
            "type": [
              "string",
              "null"
            ],
            "description": "URL slug. Null when never slugged."
          },
          "channel_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "channel_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "channel_page": {
            "type": [
              "string",
              "null"
            ],
            "description": "The channel's page on arcmira.com, absolute. Null when no channel is known."
          },
          "count": {
            "type": "integer",
            "description": "Episodes the entity came up in."
          },
          "occurrences": {
            "type": "integer",
            "description": "Times the entity came up across those episodes (mentions or appearances per mode)."
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "description": "Newest media in this count."
          }
        },
        "required": [
          "entity_id",
          "name",
          "type",
          "page",
          "appearances_page",
          "mentions_page",
          "slug",
          "channel_id",
          "channel_name",
          "channel_page",
          "count",
          "occurrences",
          "as_of"
        ]
      },
      "description": "One row per entity and channel, ranked by count."
    },
    "returned": {
      "type": "integer"
    },
    "has_more": {
      "type": "boolean",
      "description": "True when more entity and channel pairs exist past limit."
    },
    "shared": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entity_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "page": {
            "type": [
              "string",
              "null"
            ],
            "description": "The entity's page on arcmira.com, absolute. Link the name to it when you write the entity into an answer. Null for a type the site has no page for."
          },
          "appearances_page": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a person, their appearances list. Null otherwise."
          },
          "mentions_page": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a person, the mentions of them. Null otherwise."
          },
          "slug": {
            "type": [
              "string",
              "null"
            ],
            "description": "URL slug. Null when never slugged."
          },
          "channel_count": {
            "type": "integer",
            "description": "How many of the requested channels carry this entity."
          },
          "by_channel": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "channel_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "YouTube channel id."
                },
                "channel_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "channel_page": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The channel's page on arcmira.com, absolute. Null when no channel is known."
                },
                "count": {
                  "type": "integer",
                  "description": "Episodes the entity came up in."
                },
                "occurrences": {
                  "type": "integer",
                  "description": "Times the entity came up across those episodes (mentions or appearances per mode)."
                },
                "as_of": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Newest media in this count."
                }
              },
              "required": [
                "channel_id",
                "channel_name",
                "channel_page",
                "count",
                "occurrences",
                "as_of"
              ]
            }
          }
        },
        "required": [
          "entity_id",
          "name",
          "type",
          "page",
          "appearances_page",
          "mentions_page",
          "slug",
          "channel_count",
          "by_channel"
        ]
      },
      "description": "Entities on two or more of the requested channels, ranked by the smallest per-channel count. Empty for one channel."
    },
    "as_of": {
      "type": [
        "string",
        "null"
      ],
      "description": "Newest media across rows. Null when there are none."
    },
    "note": {
      "type": "string",
      "description": "One steering sentence for the agent reading this."
    }
  },
  "required": [
    "mode",
    "window",
    "channel_ids",
    "video_ids",
    "rows",
    "returned",
    "has_more",
    "shared",
    "as_of",
    "note"
  ],
  "$defs": {
    "PublicationWindow": {
      "type": "object",
      "properties": {
        "after": {
          "type": [
            "string",
            "null"
          ],
          "description": "Inclusive start as an ISO instant. Null when the window has no start."
        },
        "before": {
          "type": [
            "string",
            "null"
          ],
          "description": "Exclusive end as an ISO instant. Null when the window has no end. Earlier than the before you sent when your plan's freshness gate cut the window."
        }
      },
      "required": [
        "after",
        "before"
      ],
      "description": "The publication window the answer covers, [after, before) in UTC, normalized from after and before."
    }
  }
}