Pushing Data with the API

The API lets you push your own figures into Peaky — internal KPIs, product usage, a revenue split no standard integration offers, anything that is a number per month. Pushed figures become metrics like any other: they appear on Metrics and can be used as operands in your forecast formulas.

Unlike the other integrations, Peaky does not fetch anything here: you send the data, as often as you like, and nothing syncs by itself. Use the API for data no standard integration covers rather than duplicating what Stripe, Exact and the others already bring in.


Enable the API and Get a Key

  1. On the Integrations page, find API under the API tab and click Enable.


  2. In Enable API, click Generate API Key.


  3. Copy Your API Key with the copy button, and store it somewhere safe.

  4. Click Done. The API card is marked Connected.

The key is shown only in this dialog, and it is valid for one year. Treat it like a password: it lets anyone push data into this entity. If you lose it or it expires, remove the API integration and enable it again — the new key replaces the old one, which stops working.

The key belongs to the entity you enabled it on; enable the API on each entity you want to push to. Enable needs the integration Create right and generating the key also needs Update — with Create alone the dialog says The API is not enabled yet. Only company admins can generate an API key. See Team & Roles.


Push Data

Send a POST request to your entity's push address, with the key as a bearer token:

POST https://eu.peaky.ai/api/companies/<company>/entities/<entity>/metrics/push
Authorization: Bearer <your API key>
Content-Type: application/json

<company> and <entity> are the two parts after /company/ in Peaky's address bar when you have that entity selected in the sidebar switcher.

The body is one data point, or a list of them:

[
  {
    "slug": "ACTIVE_USERS",
    "name": "Active users",
    "type": "integer",
    "aggregationMethod": "sum",
    "period": "2026-08",
    "value": 1250,
    "dimensions": { "Plan": "Pro" }
  }
]

Field

Required

What it is

slug

Always

The metric's identifier — capital letters and underscores only, for example ACTIVE_USERS

period

Always

The month, as YYYY-MM

value

Always

A number. An integer metric only accepts whole numbers

dimensions

No

Labels to split the metric by, for example { "Plan": "Pro" }

name

For a new metric

The name shown in Peaky, up to 30 characters

type

For a new metric

currency, integer, decimal or percentage

aggregationMethod

For a new metric

sum or avg — how months add up to quarters and years

description

No

Up to 200 characters

The first push of a new slug creates the metric, so it needs name, type and aggregationMethod. Later pushes only need slug, period and value; sending a different type for an existing metric is refused. The aggregationMethod of later pushes is ignored: change it on the Metrics page instead (see Exploring Metrics). Pushing a month again replaces its value, and months you do not push are left as they are.

A successful push answers with the number of data points stored. A request that does not validate is refused with the list of problems.

When a push is refused

401 Invalid credentials means the request did not present a key that matches this company and entity. Peaky deliberately gives the same answer whichever part is wrong — an unknown company, an entity with the API switched off, or a key that is expired, mistyped or belongs to a different workspace — so that nobody can use the address to discover which companies exist. Check the company and entity in the address and that you are sending the key you generated; if you no longer have it, or the key has expired, enable the API again to get a new one.

401 Missing or invalid authorization header means the Authorization: Bearer … header is missing or malformed.


Check Your Pushes

Logs, in the API card's more menu (...), lists your pushes under Recent pushes, each marked Pushed; it shows No pushes found until the first one. There is no Sync button on the API card, because nothing is fetched. See Syncing for the logs dialog.

Push regularly to keep your model current, and check the logs after a push to confirm it arrived.

To work with your Peaky data from AI tools instead, see Connecting AI Tools (MCP).