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
On the Integrations page, find API under the API tab and click Enable.
In Enable API, click Generate API Key.
Copy Your API Key with the copy button, and store it somewhere safe.
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 |
|---|---|---|
| Always | The metric's identifier — capital letters and underscores only, for example |
| Always | The month, as |
| Always | A number. An |
| No | Labels to split the metric by, for example |
| For a new metric | The name shown in Peaky, up to 30 characters |
| For a new metric |
|
| For a new metric |
|
| 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).