Data Consolidation

Control how a user's connected providers are combined into canonical daily metrics.

When two or more providers report the same metric for the same calendar day, Sonar consolidates their values into one result. Every configurable metric has a catalog default, and each user can override that method or exclude selected providers.

The catalog is authoritative. Do not hard-code configurable metric keys or default methods in your application.

Consolidation Catalog

{
  "category_order": ["Activity", "Energy", "Body Composition", "Sleep", "Vitals", "Nutrition"],
  "metrics": [
    {
      "key": "steps",
      "display_name": "Steps",
      "category": "Activity",
      "kind": "metric",
      "default_method": "max",
      "allowed_methods": ["avg", "max", "sum"]
    },
    {
      "key": "global_sleep",
      "display_name": "Sleep",
      "category": "Sleep",
      "kind": "group",
      "default_method": "max",
      "allowed_methods": ["avg", "max", "sum"]
    }
  ]
}

A group applies one setting to its related daily metrics. Workout selection is session-based rather than numeric consolidation and is not part of this API.

Retrieve User Configuration

{
  "providers": [
    { "provider": "garmin", "enabled": true },
    { "provider": "oura", "enabled": true }
  ],
  "metrics": [
    {
      "key": "steps",
      "category": "Activity",
      "default_method": "max",
      "method": "sum",
      "overridden": true,
      "providers": [
        { "provider": "garmin", "enabled": true },
        { "provider": "oura", "enabled": false }
      ]
    }
  ]
}

The top-level provider state applies to every metric. A provider can also be excluded only for an individual metric. Metric provider state is effective state, so it is false when the provider is disabled either globally or for that metric.

Update User Configuration

response = requests.patch(
    f"{BASE}/users/{user_id}/consolidation",
    headers=HEADERS,
    json={
        "metrics": {
            "steps": {
                "method": "sum",
                "providers": {"oura": False},
            }
        },
        "providers": {"garmin": True},
    },
)
response.raise_for_status()

const response = await fetch(`${base}/users/${userId}/consolidation`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({
    metrics: {
      steps: {
        method: "sum",
        providers: { oura: false },
      },
    },
    providers: { garmin: true },
  }),
});
if (!response.ok) throw new Error(await response.text());

Set a metric’s method to null to remove its override and restore the current catalog default. Provider keys must identify providers currently connected to that user.

{
  "status": "reconsolidating",
  "configuration": {
    "providers": [],
    "metrics": []
  }
}

status is unchanged when the submitted state already matches the stored configuration.

Reset to Defaults

Errors