# 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](/doc/formula-parts-OSe8il42bj).

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**.

   ![](https://docs.peaky.ai/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzdiNTU2ZDk5LWIxMDQtNGRkNS1hNzQyLWMwOWJjMzQ2M2EzNS81YWYzZjA2ZC0xNmY3LTRlYTEtOWU0ZC02NjgxMzNjODkyMjQvTW9ub3NuYXAgSW50ZWdyYXRpb25zIC0gUGVha3kgIFBlYWt5IDIwMjYtMDItMjMgMjEtMjItMTkucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTQ5NTczMDAsImV4cCI6MTc5NTA0MzcwMH0.JnifX1DJGLrPyXSld7CBX02gza8_XO-Q15NNBPpX5m0 " =988x650")
2. In **Enable API**, click **Generate API Key**.

   ![](https://docs.peaky.ai/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzdiNTU2ZDk5LWIxMDQtNGRkNS1hNzQyLWMwOWJjMzQ2M2EzNS8wOWMzZmE1NS00ZGM2LTRmYjItOWU5YS0zZWY3YzFhNjYwN2EvTW9ub3NuYXAgSW50ZWdyYXRpb25zIC0gUGVha3kgIFBlYWt5IDIwMjYtMDItMjMgMjEtMjItNTkucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTQ5NTczMDAsImV4cCI6MTc5NTA0MzcwMH0.vOcP4YbqcJOiBbMzylTP5A0nev_PxrN0hEMJ5JRulgA " =615x333")
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](/doc/team-roles-ORspfM4rgP).


---

## 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:

```json
[
  {
    "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](/doc/exploring-metrics-ytsDb7VIaI)). 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](/doc/syncing-3ZOS5zQpM7) 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)](/doc/connecting-ai-tools-mcp-AH34CwO7Nl).