Business metrics

Push readings into a business metric from the system that counts the work: a contact-centre platform, a warehouse job, a scheduled script. A reading says how much was produced in a period and, where you measure it, how much of that was produced without a person.

POST https://{tenant}.flowstate.inc/api/v1/org/:orgId/business-metrics/readings

Permission	Rate limit
Ingest Business Metric Readings (business_metrics_ingest)	120 requests per minute per API key

Readings are live data; scenarioId is ignored.

Before you start

• The metric exists. Settings → Insights → Business Metrics shows each metric's Key, the endpoint with your organisation's URL, and the health of every feed.
• An API key with Ingest Business Metric Readings. Give a key for a feed only this permission. Create it at Settings → Users & Access → API Keys. See Authentication.

Request

One request carries one metric, one source and a batch of readings.

Field	Type	Required	Description
metric	string	Yes	The metric's key or id.
source	string	Yes	The sending system's name, e.g. "Genesys Cloud". 1–120 characters after trimming. Matched to the metric's existing sources ignoring case; created on first push if there's no match.
readings	array	Yes	1–1,000 readings.

Each reading:

Field	Type	Required	Description
periodStart	string	Yes	First day, inclusive. YYYY-MM-DD, a real calendar date.
periodEnd	string	Yes	Last day, inclusive. YYYY-MM-DD. Not before periodStart.
value	number	Yes	Output in the period, in the metric's unit. Zero or more.
aiValue	number | null	No	The part of value produced without a person. Zero or more, not more than value. Omitted or null means not measured; 0 means none.
externalRef	string | null	No	Your id for the reading. Up to 200 characters.
note	string | null	No	Shown beside the reading. Up to 2,000 characters.

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/business-metrics/readings" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "contacts-handled",
    "source": "Genesys Cloud",
    "readings": [
      {
        "periodStart": "2026-08-01",
        "periodEnd": "2026-08-31",
        "value": 48210,
        "aiValue": 9120,
        "externalRef": "genesys-2026-08"
      }
    ]
  }'

Response

200 OK:

{
  "data": {
    "metric": { "id": "cmf2k8q1x0003ab12cd34ef56", "slug": "contacts-handled" },
    "source": { "id": "cmf2k9a7b0007ab12cd34ef56", "name": "Genesys Cloud" },
    "written": 1
  }
}

metric.slug is the metric's key. written is the number of readings in the batch, all written.

Sending a period again

A reading is identified by metric, source and periodStart. Sending the same periodStart again replaces that reading's periodEnd, value, aiValue, externalRef and note; it never adds a second reading. Re-send a month, or a whole history, to correct it.

A batch is all or nothing: if any reading fails validation, none are written.

Push a month of daily readings

Send one reading per day, up to 1,000 per request. A 31-day month fits in one request.

{
  "metric": "orders-shipped",
  "source": "Warehouse nightly job",
  "readings": [
    { "periodStart": "2026-08-01", "periodEnd": "2026-08-01", "value": 1204 },
    { "periodStart": "2026-08-02", "periodEnd": "2026-08-02", "value": 1187 },
    { "periodStart": "2026-08-03", "periodEnd": "2026-08-03", "value": 962 }
  ]
}

Feed health

Settings → Insights → Business Metrics shows when each source last delivered. Two rejected readings are recorded against the source and show it as failing until the next good push: a periodEnd before periodStart, and an aiValue above value. Other invalid requests are rejected without touching the source. A source paused in Flowstate still accepts readings and stays paused.

Errors

Status	Body	When
400	VALIDATION_ERROR	The body is invalid. details[].field names the field, e.g. readings.3.periodEnd.
401	UNAUTHORIZED	The key is missing, unknown, revoked or expired.
403	FORBIDDEN	The key lacks Ingest Business Metric Readings.
404	NOT_FOUND	No metric in your organisation has that key or id: "Business metric not found: contacts-handled".
429	{ "error": "too_many_requests", "error_description": "…" }	Over 120 requests in the minute for this key. Wait Retry-After seconds.

See Errors.

Reading metrics back

There's no REST endpoint for readings. The MCP server tool get_business_metrics_summary returns every active metric with its volume, AI share and cost per unit.