{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/instasent/json-schema/instasent-analytics-series-report-schema.json",
  "title": "Series report",
  "description": "Time-bucketed arrays sharing a single continuous, zero-filled\n`date_times` axis. Every statistic array is the same length as\n`date_times` and index-aligned, with no gaps to interpolate.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/instasent-analytics-api-openapi.yml#/components/schemas/AnalyticsSeriesReport",
  "type": "object",
  "properties": {
    "resource": {
      "$ref": "#/$defs/AnalyticsResourceMeta"
    },
    "timeframe": {
      "$ref": "#/$defs/AnalyticsTimeframeResolved"
    },
    "conversion_scope": {
      "allOf": [
        {
          "$ref": "#/$defs/AnalyticsConversionScope"
        }
      ],
      "description": "Present when monetary statistics were requested."
    },
    "currency": {
      "type": "string"
    },
    "source_currency": {
      "type": "string"
    },
    "interval": {
      "allOf": [
        {
          "$ref": "#/$defs/AnalyticsInterval"
        }
      ],
      "description": "The **effective** interval after any auto-coarsening (an `interval_coarsened` warning records the change)."
    },
    "date_times": {
      "type": "array",
      "description": "The continuous bucket axis (ISO 8601). Shared by every statistic array.",
      "items": {
        "type": "string"
      }
    },
    "series": {
      "type": "object",
      "description": "Map of statistic name to a value array index-aligned with `date_times`.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "freshness": {
      "$ref": "#/$defs/AnalyticsFreshness"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AnalyticsWarning"
      }
    }
  },
  "required": [
    "timeframe",
    "currency",
    "source_currency",
    "interval",
    "date_times",
    "series",
    "freshness",
    "warnings"
  ],
  "$defs": {
    "AnalyticsChannel": {
      "type": "string",
      "title": "Channel",
      "enum": [
        "sms",
        "rcs",
        "whatsapp",
        "email"
      ]
    },
    "AnalyticsConversionScope": {
      "type": "string",
      "title": "Conversion scope",
      "description": "Which conversion scope drives revenue statistics. Projects get a\ndefault conversion configuration automatically that covers both\nscopes: `sales` is the revenue conversion and `profit` the margin\nconversion (profit amounts depend on your conversion events carrying\na margin value — without it they are `0`, not `null`). A scope is\n`null` with a `conversion_scope_unconfigured` warning only when the\nproject's configuration omits it. `lost` (abandoned) exists in\nproject configuration but is deliberately not exposed here.\n",
      "enum": [
        "sales",
        "profit"
      ],
      "default": "sales"
    },
    "AnalyticsFreshness": {
      "type": "object",
      "title": "Freshness",
      "description": "Provenance and age of the returned numbers. **Always present.**\nConsumers use `computed_at` to render \"data as of …\" and decide\nwhether to wait for a fresher value.\n",
      "properties": {
        "computed_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the numbers were produced (cache-write time for a cache hit, not the request time)."
        },
        "source": {
          "type": "string",
          "enum": [
            "cache",
            "live",
            "entity_stats"
          ],
          "description": "`cache` = overview cache; `live` = freshly computed on demand; `entity_stats` = served from cached per-entity statistics."
        },
        "stale": {
          "type": "boolean",
          "description": "True when `computed_at` is older than the family's freshness expectation."
        },
        "ttl_seconds_remaining": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Seconds until the cached value expires; `null` for non-cached sources."
        }
      },
      "required": [
        "computed_at",
        "source",
        "stale",
        "ttl_seconds_remaining"
      ]
    },
    "AnalyticsInterval": {
      "type": "string",
      "title": "Series interval",
      "description": "Time-bucket grain for series reports. Default `day`.",
      "enum": [
        "hour",
        "day",
        "week",
        "month"
      ]
    },
    "AnalyticsResourceMeta": {
      "type": "object",
      "title": "Resource metadata",
      "description": "Context about the reported entity, rich enough for an agent to write\na sensible answer without a follow-up `get_campaign` / `get_automation`\ncall. Carries the entity's public metadata fields; cached raw\nstatistics are deliberately omitted (the curated `statistics` block\nis authoritative). For rollup / overview reports this degenerates to\n`{ type }` plus the resolved scope.\n",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "campaign",
            "automation",
            "direct",
            "segment",
            "overview"
          ]
        },
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "purpose": {
          "type": "string",
          "enum": [
            "standard",
            "direct",
            "api_sms",
            "legacy"
          ]
        },
        "channel_type": {
          "$ref": "#/$defs/AnalyticsChannel"
        },
        "channel_chain": {
          "type": "array",
          "description": "Fallback chain, e.g. `[\"rcs\", \"sms\"]`; tells the consumer whether to expect per-leg fallback statistics.",
          "items": {
            "$ref": "#/$defs/AnalyticsChannel"
          }
        },
        "options_count": {
          "type": "integer",
          "description": "A/B option count. `1` means the consumer should drop A/B vocabulary."
        },
        "variants_count": {
          "type": "integer",
          "description": "Distinct variant (language) count."
        },
        "sender": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "label": {
              "type": "string"
            }
          }
        },
        "audience_contacts_count": {
          "type": "integer"
        },
        "confirmed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "activated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "archived_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "canceled_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "scheduled_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "type"
      ]
    },
    "AnalyticsTimeframeResolved": {
      "type": "object",
      "title": "Resolved timeframe",
      "description": "The resolved, hour-snapped window actually queried, echoed on every response.",
      "properties": {
        "key": {
          "type": [
            "string",
            "null"
          ],
          "description": "The predefined key when one was named; `null` for custom ranges.\n\nOne value is produced by the server and can never be requested:\n**`lifetime`**, emitted on a per-entity campaign report when the caller\nnamed no timeframe. It means the window is that campaign's own life, from\nits confirmation to the last statistics refresh, which is the window the\ncached figures actually cover. Read `start` and `end` for the real bounds\nand narrate those; do not present `lifetime` as if a period had been\nrequested, and do not compare one entity's `lifetime` against another's as\nthough they were the same window.\n"
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "description": "Hour-snapped window start (`HH:00:00.000`) in the resolved timezone."
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "description": "Hour-snapped window end (`HH:59:59.999`) in the resolved timezone."
        },
        "timezone": {
          "type": "string",
          "description": "The resolved IANA timezone (project default unless overridden)."
        }
      },
      "required": [
        "start",
        "end",
        "timezone"
      ]
    },
    "AnalyticsWarning": {
      "type": "object",
      "title": "Warning",
      "description": "Benign metadata only — never a swallowed failure. Analytics is\nfail-closed (§ error model): any real failure aborts the whole call.\n",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable warning code.",
          "enum": [
            "bounds_clamped",
            "interval_coarsened",
            "timeframe_snapped_to_hour",
            "timeframe_clamped_to_entity_lifetime",
            "conversion_scope_unconfigured",
            "retention_truncated",
            "cache_drift",
            "series_hll_not_summable",
            "partial_retention_window",
            "served_from_cached_30d_window"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation safe to relay to an end user."
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Optional structured context (e.g. requested vs applied bounds, drift percentage)."
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  }
}