{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/instasent/json-schema/instasent-analytics-values-response-schema.json",
  "title": "AnalyticsValuesResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/instasent-analytics-api-openapi.yml#/components/schemas/AnalyticsValuesResponse",
  "type": "object",
  "properties": {
    "entity": {
      "oneOf": [
        {
          "$ref": "#/$defs/AnalyticsValuesReport"
        },
        {
          "$ref": "#/$defs/AnalyticsValuesGroupedReport"
        }
      ]
    }
  },
  "required": [
    "entity"
  ],
  "$defs": {
    "AnalyticsChannel": {
      "type": "string",
      "title": "Channel",
      "enum": [
        "sms",
        "rcs",
        "whatsapp",
        "email"
      ]
    },
    "AnalyticsComparison": {
      "type": "object",
      "title": "Comparison block",
      "description": "Present only when `compare_to=previous_period`. Carries the resolved previous window, the same statistics, and per-statistic deltas (absolute + percentage).",
      "properties": {
        "timeframe": {
          "$ref": "#/$defs/AnalyticsTimeframeResolved"
        },
        "statistics": {
          "$ref": "#/$defs/AnalyticsStatisticValues"
        },
        "delta": {
          "type": "object",
          "description": "Per-statistic change. `{stat}` carries the absolute change; `{stat}_pct` the fractional change (`null` when the previous value is zero).",
          "additionalProperties": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "required": [
        "timeframe",
        "statistics",
        "delta"
      ]
    },
    "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"
      ]
    },
    "AnalyticsGroupByDimension": {
      "type": "string",
      "title": "Group-by dimension",
      "description": "A bounded breakdown dimension. `channel` / `communication_type` /\n`gender` are closed enums (all buckets returned). `country` /\n`language` / `segment` are open-cardinality (top-20 by the first\nstatistic, no overflow `other` bucket). `campaign_option` applies to\nper-entity reports. `sender` (direct rollup) and `campaign_variant`\nare **reserved** and currently return `dimension_not_yet_available`.\n",
      "enum": [
        "channel",
        "country",
        "language",
        "gender",
        "communication_type",
        "segment",
        "sender",
        "campaign_option",
        "campaign_variant"
      ]
    },
    "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"
      ]
    },
    "AnalyticsStatisticValues": {
      "type": "object",
      "title": "Statistic values",
      "description": "Map of statistic name to value. Counts are integers; rates are\nfloats with 4 decimals; currency amounts floats with 2 decimals;\nratios (`roas`, `epm`) floats with 2 decimals. Empty windows return\nexplicit zeros, never omitted keys. The only legitimate `null` is a\nstatistic whose backing conversion scope is not configured.\n",
      "additionalProperties": {
        "type": [
          "number",
          "null"
        ]
      }
    },
    "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"
      ]
    },
    "AnalyticsValuesGroupedReport": {
      "type": "object",
      "title": "Values report (grouped)",
      "description": "Aggregate totals with a single `group_by` dimension. `statistics` is\nkeyed by the dimension's values (each value a full statistics object),\n`totals_per_group` carries the cross-group roll-up (the same totals the\nflat report would return), and `group_order` makes the ranking explicit.\nOpen-cardinality dimensions return the top 20 by the first statistic (no\noverflow `other` bucket). `group_by` is single-dimension —\nmulti-dimensional / nested grouping is not supported (two or more\ndimensions are rejected).\n",
      "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"
        },
        "statistics": {
          "type": "object",
          "description": "Keyed by dimension value: `{ group: { stat: number } }`.",
          "additionalProperties": {
            "$ref": "#/$defs/AnalyticsStatisticValues"
          }
        },
        "totals_per_group": {
          "allOf": [
            {
              "$ref": "#/$defs/AnalyticsStatisticValues"
            }
          ],
          "description": "Cross-group roll-up (the same totals the flat report would return)."
        },
        "group_order": {
          "type": "array",
          "description": "Group keys in rank order.",
          "items": {
            "type": "string"
          }
        },
        "group_by": {
          "type": "array",
          "maxItems": 1,
          "items": {
            "$ref": "#/$defs/AnalyticsGroupByDimension"
          }
        },
        "freshness": {
          "$ref": "#/$defs/AnalyticsFreshness"
        },
        "warnings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AnalyticsWarning"
          }
        }
      },
      "required": [
        "resource",
        "timeframe",
        "currency",
        "source_currency",
        "statistics",
        "totals_per_group",
        "group_order",
        "group_by",
        "freshness",
        "warnings"
      ]
    },
    "AnalyticsValuesReport": {
      "type": "object",
      "title": "Values report",
      "description": "Aggregate totals over the resolved timeframe.",
      "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",
          "description": "Output currency (ISO 4217). Always present."
        },
        "source_currency": {
          "type": "string",
          "description": "Currency the monetary data is stored in before serialisation (constant `EUR` today)."
        },
        "statistics": {
          "$ref": "#/$defs/AnalyticsStatisticValues"
        },
        "comparison": {
          "$ref": "#/$defs/AnalyticsComparison"
        },
        "freshness": {
          "$ref": "#/$defs/AnalyticsFreshness"
        },
        "warnings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AnalyticsWarning"
          }
        }
      },
      "required": [
        "resource",
        "timeframe",
        "currency",
        "source_currency",
        "statistics",
        "freshness",
        "warnings"
      ]
    },
    "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"
      ]
    }
  }
}