Usage API

The Usage API exposes your project's current billing-period usage so you can build dashboards, alerts, or billing automations against it. It is a small, read-only service kept separate from the main GetMac API — a flood of usage requests will never impact your runners.

Base URL

https://usage.getmac.io/v1

A staging environment is available at https://usage-stage.getmac.io/v1.

Creating a Usage API Key

Usage API keys are project-scoped: each key reports usage for exactly one project and cannot access anything else.

1. Open the GetMac dashboard and select the project you want to monitor.
2. Go to Settings → Usage Monitoring API Keys.
3. Click Create Key, give it a name, optionally set an expiration, and click Create.
4. Copy the token that appears. You won't be able to see it again — store it somewhere safe.

To revoke a key, return to the same screen and click the trash icon. The token stops working immediately on every replica of the service.

Authentication

Pass the token in an Authorization: Bearer ... header on every request:

Authorization: Bearer <your-token>

Tokens issued for the Usage API cannot authenticate against the main GetMac API, and vice versa.

Rate limits

Every token is limited to 3 requests per second, with a small burst allowance. Exceeding the limit returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Endpoints

GET /v1/usage

Returns the current usage for the project the token is bound to.

Request

curl https://usage.getmac.io/v1/usage \
  -H "Authorization: Bearer $GETMAC_USAGE_TOKEN"

Response

{
  "project_id": "d679f235-8d7a-42f9-9802-1029ca4c61d1",
  "billing_period_start": "2026-05-01T00:00:00Z",
  "billing_period_end":   "2026-06-01T00:00:00Z",
  "instance_minutes_used":  427,
  "instance_minutes_limit": 1000,
  "instance_count_used":    1,
  "instance_count_limit":   1
}

Responses are cached for ~30 seconds. Polling more often than that won't give you fresher data — and will eat into your rate-limit budget.

GET /healthz

Unauthenticated liveness probe. Returns 200 OK with {"status":"ok"} when the service is up.

Errors

Error responses have shape:

{ "message": "human-readable description" }

Examples

Bash — alert when you reach 90% of your plan

#!/usr/bin/env bash
set -euo pipefail

response=$(curl -fsS https://usage.getmac.io/v1/usage \
  -H "Authorization: Bearer $GETMAC_USAGE_TOKEN")

used=$(jq -r '.instance_minutes_used' <<< "$response")
limit=$(jq -r '.instance_minutes_limit' <<< "$response")

pct=$(( used * 100 / limit ))
if [ "$pct" -ge 90 ]; then
  echo "WARN: GetMac compute usage at ${pct}% (${used}/${limit} min)"
  exit 1
fi

Python

import os, requests

resp = requests.get(
    "https://usage.getmac.io/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['GETMAC_USAGE_TOKEN']}"},
    timeout=5,
)
resp.raise_for_status()
data = resp.json()

print(f"Used {data['instance_minutes_used']} / "
      f"{data['instance_minutes_limit']} minutes")

Go

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type Usage struct {
	InstanceMinutesUsed  int64 `json:"instance_minutes_used"`
	InstanceMinutesLimit int64 `json:"instance_minutes_limit"`
	InstanceCountUsed    int64 `json:"instance_count_used"`
	InstanceCountLimit   int64 `json:"instance_count_limit"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://usage.getmac.io/v1/usage", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("GETMAC_USAGE_TOKEN"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var u Usage
	if err := json.NewDecoder(resp.Body).Decode(&u); err != nil {
		panic(err)
	}

	fmt.Printf("Used %d / %d minutes\n",
		u.InstanceMinutesUsed, u.InstanceMinutesLimit)
}

FAQ

Can I list usage for multiple projects with one token? No. Each key is bound to one project. Create one key per project.

Will my Usage API token work against api.getmac.io? No. Usage tokens are issued with a separate scope and are rejected by the main API. This is deliberate — it means a leaked usage token cannot create instances, change billing, or do anything other than read usage for its one project.

How fresh is the data? Counters are computed live with a small in-service cache (~30 seconds) to absorb traffic spikes. Running instances are pro-rated to the current time.

What happens when I revoke a key? Existing tokens are checked against the database on every request, so revocation takes effect immediately on every replica of the service.