# Read your metrics

> Your jobs and calls in `[start, end)`, one row per group — the whole account: job counts and outcomes, queue and run time percentiles, credits charged and the calls your API keys made.

`GET https://api.refabric.com/v1/account/metrics`

**Modes**

- `group_by=day` · `task` · `key` · `error` — one row per UTC day, task, API key, or public error code (the jobs that ended with it and the calls answered with it).

**Authentication.** A key with `account:read`: the figures are your account's.

**Key features**

- A window of 90 days at most.
- Call counts cover the API-key calls of the last 30 days.

**Common use cases**

- Chart your traffic and spend per day.
- Find the error code your integration hits most.

**See also**

- `GET /v1/account/usage`
- `GET /v1/account/requests`
- `GET /v1/errors`

Authentication: `Authorization: Key $REFABRIC_API_KEY`, scope `account:read`.

## Query parameters

- `group_by` (string, _optional_, default: `day`) — One row per UTC `day`, per `task` (the public name), per `key`, or per `error` (a public error code: the jobs that ended with it and the calls answered with it).
  Values: `day` (One row per UTC day.); `task` (One row per task.); `key` (One row per API key.); `error` (One row per public error code.)
- `start` (string | null, _optional_, format: date-time) — Inclusive, ISO-8601 (`2026-09-01T00:00:00Z`; no zone means UTC). Default: 30 days before `end`. The window is at most 90 days.
- `end` (string | null, _optional_, format: date-time) — Exclusive, ISO-8601 (no zone means UTC). Default: now.

## Header parameters

- `Refabric-Version` (string, _optional_, format: date) — The contract version you wrote against (a date). Absent: the current version.
- `X-Request-ID` (string, _optional_, max length 128) — Your own id for this request; we answer it back under X-Client-Request-ID.

## Response 200

Done: the answer is in the body.

- `as_of` (string, _required_) — The moment these figures were read (UTC, ISO-8601).
  Example: `2026-10-01T00:00:00Z`
- `start` (string, _required_) — The window's first instant, inclusive (UTC).
  Example: `2026-09-01T00:00:00Z`
- `end` (string, _required_) — The window's end, exclusive (UTC); without `end` sent, `as_of`.
  Example: `2026-10-01T00:00:00Z`
- `group_by` (string, _required_) — How the rows are grouped, as asked.
  Values: `day` (One row per UTC day.); `task` (One row per task.); `key` (One row per API key.); `error` (One row per public error code.)
  Example: `day`
- `items` (array<object>, _required_) — One row per group, ordered by the group.
  - `jobs` (integer, _required_) — Jobs submitted in the group.
    Example: `12`
  - `succeeded` (integer, _required_) — Jobs that finished with a result.
    Example: `10`
  - `failed` (integer, _required_) — Jobs that ended with an error.
    Example: `1`
  - `cancelled` (integer, _required_) — Jobs that were cancelled.
    Example: `1`
  - `wait_ms` (object, _required_) — Queue time: from the moment a job was accepted to the moment it started running.
    Example: `{"p50":900,"p95":4100}`
    - `p50` (integer | null, _required_) — The median.
      Example: `900`
    - `p95` (integer | null, _required_) — The 95th percentile.
      Example: `4100`
  - `run_ms` (object, _required_) — Run time: from the moment a job started running to the moment it ended.
    Example: `{"p50":21000,"p95":48000}`
    - `p50` (integer | null, _required_) — The median.
      Example: `900`
    - `p95` (integer | null, _required_) — The 95th percentile.
      Example: `4100`
  - `credits` (integer, _required_) — Credits charged for the group's jobs.
    Example: `110`
  - `http` (object, _required_) — The calls your API keys made in the group (API-key calls only).
    Example: `{"client_errors":3,"rate_limited":1,"requests":40,"server_errors":0}`
    - `requests` (integer, _required_) — Calls made with your API keys.
      Example: `40`
    - `client_errors` (integer, _required_) — Calls answered with a 4xx status.
      Example: `3`
    - `server_errors` (integer, _required_) — Calls answered with a 5xx status.
      Example: `0`
    - `rate_limited` (integer, _required_) — Calls answered 429 (over the rate limit).
      Example: `1`
  - `day` (string | null, _optional_) — The UTC day (`group_by=day`).
    Example: `2026-09-30`
  - `task` (string | null, _optional_) — The task's public name (`group_by=task`).
    Example: `image.generate`
  - `api_key_id` (string | null, _optional_) — The API key (`group_by=key`); `null` for work started in the Refabric app.
    Example: `key_8f3a`
  - `error` (string | null, _optional_) — A public error code (`group_by=error`), as `GET /v1/errors` lists it.
    Example: `invalid_option`

```json
{
  "as_of": "2026-10-01T00:00:00Z",
  "start": "2026-09-01T00:00:00Z",
  "end": "2026-10-01T00:00:00Z",
  "group_by": "day",
  "items": []
}
```

## Response 400

The request cannot be read as it was sent (a header, the URL or the body's form).

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 401

No valid API key was sent.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 403

Your key or your plan does not allow this.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 422

A field is missing or has a value this operation cannot use.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 429

Too many requests: wait for the number of seconds in the Retry-After header.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 500

Something went wrong on our side; retry, and quote the request id if it keeps happening.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Request

```python
import os
import requests

url = "https://api.refabric.com/v1/account/metrics"

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.refabric.com/v1/account/metrics';
const options = {method: 'GET', headers: {Authorization: `Key ${process.env.REFABRIC_API_KEY}`}};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}
```

```bash
curl --request GET \
    --url https://api.refabric.com/v1/account/metrics \
    --header "Authorization: Key $REFABRIC_API_KEY"
```