Check your usage and limits

You are viewing in-progress documentation for v2 (Beta). Switch to the stable version for the current production release.

Your account has usage quotas — ceilings on how many jobs you can run at once, how many resources you can own, how many bytes they store, and how long they are kept. This guide shows how to read your own live numbers: two endpoints report them, and they are the authoritative answer to “what are my limits, and how close am I?” Never hard-code limit values into client code — read them here, because tiers and per-account overrides mean your numbers can differ from anyone else’s and can change over time.

For the concepts behind these numbers — what each dimension means and why it exists — see the explanation page About usage quotas. This guide is the procedural companion: the calls and how to read them.

Prerequisites

An API key. Create one in the FastFuels web app under your account settings. Set it once here: my-api-key. It propagates to every code block on this page.

See your limits

GET /users/me returns who you are, your tier, and your fully-resolved limits — the tier defaults with any per-account overrides already merged in. This is the canonical list of ceilings your account is held to. The example response below shows the standard-tier defaults; your own call returns whatever applies to your account.

curl -X 'GET' \
  'https://api-v2-prod-nyvjyh5ywa-uw.a.run.app/users/me' \
  -H 'accept: application/json' \
  -H 'api-key: my-api-key'

import requests

url = "https://api-v2-prod-nyvjyh5ywa-uw.a.run.app/users/me"

headers = {
    "accept": "application/json",
    "api-key": "my-api-key",
}

response = requests.get(url, headers=headers)
response.raise_for_status()
me = response.json()

tier = me["tier"]
quotas = me["quotas"]
print(f"tier: {tier}")
print(f"max concurrent grid jobs: {quotas['max_active_grids']}")
print(f"max domains: {quotas['max_domains']}")

{
  "id": "owner-abc123",
  "kind": "user",
  "tier": "standard",
  "quotas": {
    "max_active_grids": 25,
    "max_active_exports": 10,
    "max_active_inventories": 10,
    "max_active_features": 10,
    "max_active_pointclouds": 5,
    "max_domains": 50,
    "max_grids": 1000,
    "max_exports": 500,
    "max_inventories": 500,
    "max_features": 500,
    "max_pointclouds": 50,
    "max_api_keys": 50,
    "max_applications": 5,
    "max_grid_storage_bytes": 53687091200,
    "max_export_storage_bytes": 26843545600,
    "max_inventory_storage_bytes": 10737418240,
    "max_feature_storage_bytes": 1073741824,
    "max_pointcloud_storage_bytes": 53687091200,
    "resource_ttl_days": 180,
    "failed_resource_ttl_days": 14
  }
}

The quotas object groups into the four dimensions the explanation page describes:

max_active_* — how many jobs of a type may be in progress at once.
max_domains, max_grids, … — how many of each type you may own.
max_*_storage_bytes — total stored bytes per type (the human number is bytes ÷ 2³⁰ = GiB).
resource_ttl_days / failed_resource_ttl_days — how long resources are retained before automatic reclamation (null means never).

See your usage against those limits

GET /users/me/usage pairs each limit with your current usage, so you can see the headroom left before any ceiling — plus a lifecycle block echoing your retention settings.

curl -X 'GET' \
  'https://api-v2-prod-nyvjyh5ywa-uw.a.run.app/users/me/usage' \
  -H 'accept: application/json' \
  -H 'api-key: my-api-key'

import requests

url = "https://api-v2-prod-nyvjyh5ywa-uw.a.run.app/users/me/usage"

headers = {
    "accept": "application/json",
    "api-key": "my-api-key",
}

response = requests.get(url, headers=headers)
response.raise_for_status()
usage = response.json()

# How much grid headroom is left before the active-job limit?
grids = usage["grids"]["active"]
remaining = grids["limit"] - grids["usage"]
print(f"grid jobs in progress: {grids['usage']}/{grids['limit']} ({remaining} free)")

# Are any resources close to a storage ceiling?
for kind in ("grids", "exports", "inventories", "features", "pointclouds"):
    storage = usage[kind]["storage"]
    pct = 100 * storage["usage_bytes"] / storage["limit_bytes"]
    print(f"{kind} storage: {pct:.1f}% of limit")

{
  "grids": {
    "active": { "usage": 3, "limit": 25 },
    "total": { "usage": 214, "limit": 1000 },
    "storage": { "usage_bytes": 8123400000, "limit_bytes": 53687091200 }
  },
  "exports": {
    "active": { "usage": 0, "limit": 10 },
    "total": { "usage": 5, "limit": 500 },
    "storage": { "usage_bytes": 402653184, "limit_bytes": 26843545600 }
  },
  "inventories": {
    "active": { "usage": 1, "limit": 10 },
    "total": { "usage": 40, "limit": 500 },
    "storage": { "usage_bytes": 1073741824, "limit_bytes": 10737418240 }
  },
  "features": {
    "active": { "usage": 0, "limit": 10 },
    "total": { "usage": 8, "limit": 500 },
    "storage": { "usage_bytes": 160972, "limit_bytes": 1073741824 }
  },
  "pointclouds": {
    "active": { "usage": 0, "limit": 5 },
    "total": { "usage": 0, "limit": 50 },
    "storage": { "usage_bytes": 0, "limit_bytes": 53687091200 }
  },
  "domains": {
    "total": { "usage": 12, "limit": 50 }
  },
  "applications": {
    "total": { "usage": 1, "limit": 5 }
  },
  "api_keys": {
    "total": { "usage": 2, "limit": 50 }
  },
  "lifecycle": {
    "resource_ttl_days": 180,
    "failed_resource_ttl_days": 14,
    "next_expiry_on": null
  }
}

Each resource entry pairs a usage with the limit it counts against:

active — jobs in progress now (usage) vs the concurrency limit (limit). This is the number that clears on its own as jobs finish.
total — resources owned (usage) vs the count limit (limit).
storage — usage_bytes vs limit_bytes.

Count-only types — domains, applications, and api_keys — carry just a total. The top-level lifecycle block repeats your two retention TTLs and next_expiry_on.

Read the numbers

The usage response answers the practical questions directly:

“Can I start more grid jobs right now?” — compare grids.active.usage to grids.active.limit; the difference is how many more you can launch before a 429.
“Am I running low on storage?” — compare each type’s storage.usage_bytes to limit_bytes.
“How many domains can I still create?” — domains.total.limit minus domains.total.usage.

Checking this before a create is how you plan around a ceiling rather than discovering it by hitting one.

When you’re near a limit

If a create call is refused, the API returns a structured 429 QUOTA_EXCEEDED naming the exact quota, your current value, and the limit. How you free capacity depends on the dimension:

Active-job limit — the response carries a Retry-After header; wait for in-flight jobs to finish (or delete a running one you don’t need), then retry.
Count or storage limit — no Retry-After; delete resources you no longer need to free slots or bytes. Idle resources also expire automatically on the retention clock.
Need more headroom permanently — contact support.fastfuels@silvxlabs.com to have your tier or a specific limit raised.

Where to go next

About usage quotas — the concepts behind every number on this page: the four dimensions, tiers and overrides, retention, and the full 429 QUOTA_EXCEEDED model.
Create a domain — the first resource you create under your account, and the first place a quota can apply.