Metrics Exchange API.

1. What it is

Health Monitor API →

Whoever owns a set of data in Manager.Social ticks the numbers they are willing to share. A receiving system logs in, asks for those numbers for any date range, and gets them as JSON, XML or CSV. It never has to know the numbers in advance: a catalogue tells it every number's name, unit and meaning, and a dry run returns the exact shape of a real answer with zeros in it, so you can build and test your mapping before any real data flows.

A data client is one receiver's credentials, with a scope (the platform, an organisation or a workspace — fixed when the client is created, never taken from your request), a selection (which metrics and breakdowns were ticked) and settings (token lifetime, freshness, timezone, currency mode, formats). The data owner creates and manages clients in their console; you receive a client id and a secret, shown once.

Common rules

• Base URL https://manager.social/metrics-exchange/v1. HTTPS only.
• Every response carries X-Request-Id. Every data document carries query_id.
• Every endpoint except /token and /token/revoke requires Authorization: Bearer <token>; those two authenticate with the client id and secret.
• Every timestamp is ISO 8601 with offset. Dates in requests are interpreted in the client's timezone. Week grouping starts on Monday (ISO 8601).
• Choose the format with the format=json|xml|csv query parameter, or Accept: application/json | application/xml | text/csv. Default JSON. Errors are always Problem Details JSON regardless of the requested format.
• Version 1 only ever changes by adding. A breaking change would be a new /v2/ path.

2. The five doors

In the order a receiver uses them:

Your only write is POST /token/revoke, to kill a token you believe has leaked; everything else about a client (selection, secrets, deletion) belongs to the data owner's console.

GET /health

Besides uptime, /health reports your client's setup, so you can verify your configuration on every heartbeat.

{
  "status": "ok",
  "contract": "metrics-exchange/1",
  "provider": "example.provider",
  "server_time": "2026-10-16T05:07:05Z",
  "data_as_of": "2026-10-16T05:05:00Z",
  "client": {
    "name": "BI production",
    "scope": { "level": "platform", "id": null, "name": "Example" },
    "metrics_enabled": 9,
    "formats": ["json", "xml", "csv"],
    "freshness_seconds": 300,
    "token_lifetime_seconds": 3600,
    "timezone": "Asia/Kolkata"
  }
}

status: ok, degraded (data delayed beyond freshness), down. When metrics_enabled changes, refetch /catalogue.

3. Tokens

POST /token

OAuth 2 client credentials (RFC 6749 §4.4). Form or JSON: grant_type=client_credentials, client_id, client_secret.

curl -s -X POST 'https://manager.social/metrics-exchange/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>'

{ "access_token": "mx_at_…", "token_type": "Bearer", "expires_in": 3600, "scope": "metrics:read" }

• Tokens are opaque; do not parse them. Renew before expires_in.
• Token lifetime is set per client, 5 minutes to 24 hours, default 1 hour.
• A revoked client's tokens die immediately.
• Requests are limited per caller (20 per minute, IP + client id) and, on top, per address (60 per minute across /token and /token/revoke, whatever the client id) → RATE_LIMITED with Retry-After.
• While the administrator switch for every level is off, every client gets INVALID_CLIENT without its credentials being checked.

POST /token/revoke

RFC 7009. Form or JSON: token, plus client_id and client_secret. The answer is always 200 {}, even for an unknown token — except past the per-caller limit (20 per minute) or the per-address limit (60 per minute across /token and /token/revoke), which answer 429 RATE_LIMITED with Retry-After.

curl -s -X POST 'https://manager.social/metrics-exchange/v1/token/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=<token>&client_id=<client_id>&client_secret=<client_secret>'

4. Time windows

GET /time returns the provider clock, your client's timezone, data_as_of and the exact resolved window for every shortcut. /data echoes the same period, so "today" means the same thing on both sides.

{
  "server_time": "2026-10-16T10:37:05+05:30",
  "server_time_utc": "2026-10-16T05:07:05Z",
  "timezone": "Asia/Kolkata",
  "utc_offset": "+05:30",
  "data_as_of": "2026-10-16T10:35:00+05:30",
  "week_starts_on": "monday",
  "shortcuts": {
    "today":       { "from": "2026-10-16T00:00:00+05:30", "to": "2026-10-17T00:00:00+05:30" },
    "yesterday":   { "from": "2026-10-15T00:00:00+05:30", "to": "2026-10-16T00:00:00+05:30" },
    "this_week":   { "from": "2026-10-12T00:00:00+05:30", "to": "2026-10-19T00:00:00+05:30" },
    "last_7_days": { "from": "2026-10-09T00:00:00+05:30", "to": "2026-10-16T00:00:00+05:30" },
    "this_month":  { "from": "2026-10-01T00:00:00+05:30", "to": "2026-11-01T00:00:00+05:30" },
    "last_month":  { "from": "2026-09-01T00:00:00+05:30", "to": "2026-10-01T00:00:00+05:30" }
  }
}

• Optional ?timezone=<IANA> if the client allows overrides; the shortcuts are then resolved in that zone.
• to is always exclusive.
• last_7_days excludes today; this_week and this_month include it.
• date=2026-10-15 is exactly that day in the client’s timezone — the simplest way to ask for one day’s numbers.
• Call /time once a day, and after any clock or daylight-saving doubt.

5. Catalogue & metrics

GET /catalogue lists only the metrics and breakdowns ticked for your client. Every metric carries a sample_point — a point of the right kind with zero values — so you can map fields from the catalogue alone.

{
  "contract": "metrics-exchange/1",
  "provider": "example.provider",
  "scope": { "level": "organisation", "id": "org_…", "name": "Acme Ltd" },
  "timezone": { "default": "Asia/Kolkata", "override_allowed": true },
  "currency_mode": "single",
  "currency": "USD",
  "groupings": ["hour", "day", "week", "month"],
  "shortcuts": ["today", "yesterday", "this_week", "last_7_days", "this_month", "last_month"],
  "formats": ["json", "xml", "csv"],
  "limits": { "max_points": 10000, "requests_per_day": 1000 },
  "template": "revenue",
  "metrics": [
    {
      "id": "revenue", "version": 1,
      "label": "Revenue",
      "description": "Successful payments in the period, in USD at time of purchase. Includes test payments.",
      "unit": "currency", "kind": "sum",
      "breakdowns": ["region"],
      "status": "active", "available_from": "2026-01-01", "withdrawn_on": null,
      "sample_point": { "start": "…", "end": "…", "value": "0.00", "currency": "USD", "final": false, "breakdown": null }
    }
  ]
}

• unit ∈ count, currency, percent, seconds, bytes.
• kind ∈ count, sum, distinct, ratio, gauge. Only count and sum may be summed across periods; ratio sends numerator and denominator; gauge is a value at period end.
• currency_mode is single (with currency) or per_currency. Money is a decimal string and always carries its currency.
• template names the template the client started from, or null; it is informational only.
• Ids are permanent and carry a definition version: a changed meaning is a new id. Withdrawn metrics get 30 days' notice through withdrawn_on and notices.
• Ranges before a metric's available_from return RANGE_BEFORE_AVAILABLE, never a silent zero.

Metrics Manager.Social offers

Every metric below is version 1 and includes all data, including test and internal accounts. Your catalogue shows only the ones ticked for your client and allowed at its scope.

6. Data

GET /data and POST /data take the same parameters; POST takes them as a JSON body, for long metric lists.

curl -s 'https://manager.social/metrics-exchange/v1/data?metrics=signups,credits_spent&range=last_7_days&group=day' \
  -H 'Authorization: Bearer <token>'

curl -s -X POST 'https://manager.social/metrics-exchange/v1/data' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{ "metrics": ["signups", "credits_spent"], "from": "2026-10-01", "to": "2026-10-08", "group": "day" }'

Shortcuts, grouping and breakdowns

• Shortcuts: today, yesterday, this_week, last_7_days, this_month, last_month. Give range or from/to, never both (INVALID_RANGE).
• group: hour, day, week (Monday start), month; omitted gives one total per metric.
• breakdown splits a metric by one dimension it offers (see the catalogue). Breakdown points carry "breakdown": { "name": "company", "value": "…" }; groups smaller than 5 merge into "Other".
• A point may carry a note such as unconverted_count when part of a sum could not be expressed in the reporting currency; notes never replace the value.

Dry run

dry_run=true returns the full document for the requested metrics and range with zero values and "dry_run": true, without touching the database. A dry run counts as 0.1 of a request against the daily limit. Test your pipeline with it before go-live.

JSON (master shape)

{
  "contract": "metrics-exchange/1",
  "query_id": "mxq_01J…",
  "dry_run": false,
  "provider": "example.provider",
  "scope": { "level": "workspace", "id": "ws_…", "name": "Northern region" },
  "generated_at": "2026-10-16T10:37:05+05:30",
  "data_as_of": "2026-10-16T10:35:00+05:30",
  "timezone": "Asia/Kolkata",
  "period": { "from": "2026-10-16T00:00:00+05:30", "to": "2026-10-17T00:00:00+05:30", "group": "day", "range": "today" },
  "metrics": [
    { "id": "orders", "version": 1, "label": "Orders", "unit": "count", "kind": "count",
      "points": [ { "start": "2026-10-16T00:00:00+05:30", "end": "2026-10-17T00:00:00+05:30", "value": "412", "final": false, "breakdown": null } ] },
    { "id": "fulfilment_rate", "version": 1, "label": "Fulfilment rate", "unit": "percent", "kind": "ratio",
      "points": [ { "start": "…", "end": "…", "value": "93.10", "numerator": "384", "denominator": "412", "final": false, "breakdown": null } ] }
  ],
  "notices": [ { "metric": "old_metric", "type": "withdrawn", "on": "2026-11-15" } ],
  "next_page": null
}

XML

The same tree with fixed element names, validated by /schema.xsd. <next_page> appears only when a next page exists; a point's optional fields are child elements <currency>, <numerator>, <denominator>, <unconverted_count> and <breakdown name="…" value="…"/> after <value>; notices are <notice metric="…" type="…" on="…"/>. Content type application/xml; charset=utf-8.

<?xml version="1.0" encoding="UTF-8"?>
<metrics-exchange contract="1">
  <query_id>mxq_01J…</query_id> <dry_run>false</dry_run> <provider>example.provider</provider>
  <scope level="workspace" id="ws_…" name="Northern region"/>
  <generated_at>…</generated_at> <data_as_of>…</data_as_of> <timezone>Asia/Kolkata</timezone>
  <period from="…" to="…" group="day" range="today"/>
  <metrics>
    <metric id="orders" version="1" label="Orders" unit="count" kind="count">
      <point start="…" end="…" final="false"><value>412</value></point>
    </metric>
  </metrics>
  <notices/>
</metrics-exchange>

CSV

Long format, one row per point, UTF-8 without BOM, LF line endings, booleans true/false, content type text/csv; charset=utf-8. An empty cell means not applicable. CSV has no notices; poll JSON or watch /health for them. The header row:

query_id,dry_run,metric_id,metric_version,label,unit,kind,start,end,value,currency,numerator,denominator,final,breakdown_name,breakdown_value,timezone,data_as_of

Formats

format= wins over Accept. An unknown format= value, or a format not enabled for your client, is 406 FORMAT_NOT_ALLOWED; an Accept header naming none of the three media types falls back to JSON.

Paging

A response holds at most 10,000 points, and larger answers are paged. A request whose grouping alone would need more points fails with TOO_MANY_POINTS, carrying a suggested_group (a coarser grouping that fits). When there is more, the JSON next_page (XML <next_page>) holds an opaque cursor, and every format also sends it in headers:

X-Next-Page: <cursor>
Link: <…/data?<the same query>&page=<cursor>>; rel="next"

A cursor is valid only with the same query: repeat the query with page=<cursor> (the Link header already does). A paged answer is a snapshot valid for 15 minutes; an expired or mismatched next_page cursor returns INVALID_RANGE — restart from the first page.

Receiver rules

• Upsert on (metric id, start, breakdown); never append.
• Treat final: false as provisional, and final: true as closed but not frozen — it can still decrease when source rows are permanently erased.
• Never sum distinct, ratio, gauge across periods.
• Render unknown metrics from the catalogue (label, unit, kind, sample_point).
• Pull no faster than the client's freshness interval (1–60 minutes, default 5).

Receiver checklist

1. Store id and secret; get a token; renew before expiry.
2. Call /time once a day (and after any clock or DST doubt) to learn the exact windows.
3. Call /catalogue once a day, on METRIC_NOT_ALLOWED, and when /health.client.metrics_enabled changes. Build KPI cards from label, unit, kind, sample_point.
4. Test your pipeline with dry_run=true before go-live.
5. Pull /data no faster than the freshness interval. Upsert. Show provisional points as such.
6. Watch notices for withdrawals.

7. Errors

Problem Details (RFC 9457), always JSON, whatever format you asked for:

{ "type": "https://<provider>/metrics-exchange/errors/METRIC_NOT_ALLOWED", "title": "Metric not available to this client",
  "status": 403, "code": "METRIC_NOT_ALLOWED", "detail": "…", "query_id": "mxq_…", "request_id": "…" }

An unknown path or method under /metrics-exchange/v1 answers 404 Problem Details with code NOT_FOUND (and X-Request-Id); it is not part of the contract table above.

8. Limits

Free, with fair-use limits. These are the defaults; the console shows the values in force. Over a limit → RATE_LIMITED with Retry-After, never partial data.

9. OpenAPI, XSD & conformance

• GET /openapi.json — the OpenAPI 3.1 description of every endpoint and response. It is the arbiter of the contract.
• GET /schema.xsd — the XML schema every XML document validates against.

Both are served at https://manager.social/metrics-exchange/v1/openapi.json and https://manager.social/metrics-exchange/v1/schema.xsd and need a bearer token, like every data endpoint:

curl -s 'https://manager.social/metrics-exchange/v1/openapi.json' -H 'Authorization: Bearer <token>' -o openapi.json
curl -s 'https://manager.social/metrics-exchange/v1/schema.xsd'   -H 'Authorization: Bearer <token>' -o schema.xsd

Conformance script

A small script (Python 3 plus requests), run against a base URL and credentials. It checks, in order: token issue and expiry; the /health shape; /time windows contiguous and in the stated zone; a valid sample_point for every catalogue metric; the dry run matching the catalogue; real /data in all three formats validating against openapi.json and schema.xsd; every error code reproducible; the point cap triggering TOO_MANY_POINTS; suppression yielding Other. It exits non-zero on any failure. The script is not published on a public URL yet — ask us for the conformance script.

10. Quickstart

With the client id and secret from the data owner, these four calls take you from a token to a dry-run document. Replace the <…> placeholders; the token comes from step 1's access_token.

# 1. Get a token (client credentials)
curl -s -X POST 'https://manager.social/metrics-exchange/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>'

# 2. Check the clock and the time windows
curl -s 'https://manager.social/metrics-exchange/v1/time' -H 'Authorization: Bearer <token>'

# 3. See the metrics this client may read
curl -s 'https://manager.social/metrics-exchange/v1/catalogue' -H 'Authorization: Bearer <token>'

# 4. Dry run: the document shape with zero values
curl -s 'https://manager.social/metrics-exchange/v1/data?metrics=*&range=last_7_days&dry_run=true' -H 'Authorization: Bearer <token>'

Then drop dry_run=true to get real numbers, add group=day for a daily series, or format=csv for a spreadsheet-friendly answer. Questions: [email protected].