{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/multi-upload-tool-com/json-schema/multi-upload-tool-com-analytics-schema.json",
  "title": "Analytics",
  "description": "What the collector holds for the accounts in scope. Every metric is a running total read from the platform, not a per-day figure.",
  "x-generated": "2026-11-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/multi-upload-tool-com-openapi.json#/components/schemas/Analytics",
  "type": "object",
  "properties": {
    "overview": {
      "type": "object",
      "properties": {
        "totalViews": {
          "type": "integer"
        },
        "totalLikes": {
          "type": "integer"
        },
        "totalComments": {
          "type": "integer"
        },
        "totalShares": {
          "type": "integer"
        },
        "videoCount": {
          "type": "integer"
        },
        "accountCount": {
          "type": "integer"
        },
        "bestAccount": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "platform": {
              "$ref": "#/$defs/Platform"
            },
            "views": {
              "type": "integer"
            }
          }
        }
      }
    },
    "videos": {
      "type": "array",
      "description": "One row per tracked post, with its metrics, an `isTrending` flag and `source`: `mut` if it was published through Multi Upload Tool, `external` if it was posted directly on the platform.",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "bestPerforming": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "mostViewed": {
          "type": "object",
          "additionalProperties": true
        },
        "mostEngaging": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "topHashtags": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "postingInsights": {
      "$ref": "#/$defs/PostingInsights"
    },
    "dailyHistory": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "platformHistory": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "summary": {
      "type": "object",
      "description": "The last 30 days against the 30 before. `null` means not measured, never zero.",
      "properties": {
        "windowDays": {
          "type": "integer",
          "const": 30
        },
        "views": {
          "type": "object",
          "description": "Views gained in each period, summed from the daily series (gaps spread evenly, as on the chart). `measuredDays` says how many days of each period had data.",
          "properties": {
            "current": {
              "type": [
                "integer",
                "null"
              ]
            },
            "previous": {
              "type": [
                "integer",
                "null"
              ]
            },
            "change": {
              "type": [
                "integer",
                "null"
              ]
            },
            "changePct": {
              "type": [
                "number",
                "null"
              ]
            },
            "measuredDays": {
              "type": "object",
              "properties": {
                "current": {
                  "type": "integer"
                },
                "previous": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "followers": {
          "type": "object",
          "description": "`total` = latest follower count summed over accounts. `change` only counts accounts that were also measured 30 days ago, so it stays `null` for the first 30 days of history.",
          "properties": {
            "total": {
              "type": [
                "integer",
                "null"
              ]
            },
            "previous": {
              "type": [
                "integer",
                "null"
              ]
            },
            "change": {
              "type": [
                "integer",
                "null"
              ]
            },
            "changePct": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        },
        "postsPublished": {
          "type": "object",
          "properties": {
            "current": {
              "type": "integer"
            },
            "previous": {
              "type": "integer"
            },
            "change": {
              "type": "integer"
            }
          }
        }
      }
    },
    "followerHistory": {
      "type": "array",
      "description": "One point per day over the window: the sum of each account's last known follower count. Days before the first reading are omitted.",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "followers": {
            "type": "integer"
          }
        }
      }
    },
    "accountTags": {
      "type": "array",
      "description": "Only on the single-account route.",
      "items": {
        "type": "string"
      }
    },
    "lastRefreshedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the collector last read the platform. Show it next to the numbers."
    },
    "neverSynced": {
      "type": "boolean",
      "description": "`true` means nothing has ever been collected, as opposed to collected and empty. The two deserve different messages: \"connect and wait for tonight\" is not \"you have no posts yet\"."
    },
    "syncErrors": {
      "type": "array",
      "description": "Accounts whose last collection failed. A failing account never stops the others.",
      "items": {
        "type": "object",
        "properties": {
          "accountName": {
            "type": "string"
          },
          "platform": {
            "$ref": "#/$defs/Platform"
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  },
  "$defs": {
    "Platform": {
      "type": "string",
      "description": "A supported social platform.",
      "enum": [
        "tiktok",
        "youtube",
        "instagram",
        "facebook",
        "linkedin",
        "pinterest",
        "bluesky",
        "threads",
        "x"
      ]
    },
    "PostingBucket": {
      "type": "object",
      "description": "One weekday or one hour of day, averaged over the posts that landed in it.",
      "properties": {
        "weekday": {
          "type": "integer",
          "minimum": 0,
          "maximum": 6,
          "description": "0 = Sunday, following Postgres' `dow`. Present on `byWeekday` and `bestDay`."
        },
        "hour": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23,
          "description": "Hour of day in the requested timezone. Present on `byHour` and `bestHours`."
        },
        "posts": {
          "type": "integer"
        },
        "avgViews": {
          "type": "integer"
        },
        "ranked": {
          "type": "boolean",
          "description": "False when `posts` is under `minSamples`. The bucket keeps its average — it is worth showing — but it is never eligible to win. One lucky post is a coincidence, not a slot, and it is the loudest one: a single viral video gives its bucket an average no honest bucket can beat."
        }
      }
    },
    "PostingInsights": {
      "type": "object",
      "description": "When this account has published, and what those slots averaged. Derived from the posts already collected, so it says nothing until there are enough of them.",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "The zone the buckets were read in — whatever you asked for, or `UTC`."
        },
        "minSamples": {
          "type": "integer",
          "description": "Posts a bucket needs before it can be ranked."
        },
        "byWeekday": {
          "type": "array",
          "description": "Always 7 entries, Sunday first, including the days with nothing in them.",
          "items": {
            "$ref": "#/$defs/PostingBucket"
          }
        },
        "byHour": {
          "type": "array",
          "description": "Always 24 entries, 00:00 first.",
          "items": {
            "$ref": "#/$defs/PostingBucket"
          }
        },
        "bestDay": {
          "oneOf": [
            {
              "$ref": "#/$defs/PostingBucket"
            },
            {
              "type": "null"
            }
          ]
        },
        "bestHours": {
          "type": "array",
          "description": "Up to 5 hours, best first. Ranked buckets only.",
          "items": {
            "$ref": "#/$defs/PostingBucket"
          }
        },
        "sampleSize": {
          "type": "integer",
          "description": "Posts carrying a publication date, i.e. what the buckets were built from."
        }
      }
    }
  }
}