# Usage & health

Check your metered usage for the current billing period, and probe service health.

## Usage

```
GET /usage
```

Authentication: Bearer API key required.

Return billed-action counts by kind: all time and for the current period, with the pages and context tokens metered under each kind.

```curl
curl https://api.getemboss.ai/usage \
  -H "Authorization: Bearer sk_..."
```

```js
const res = await fetch("https://api.getemboss.ai/usage", {
  headers: { Authorization: "Bearer sk_..." },
});
const usage = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.getemboss.ai/usage",
    headers={"Authorization": "Bearer sk_..."},
)
usage = res.json()
```

### Response

```json
{
  "owner": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "email": "you@example.com",
  "period": "2026-09",
  "total": { "create": 12, "with_context": 4, "standard_fill": 3, "verify": 2, "read": 1, "package": 0, "send_fax": 2, "utility": 4 },
  "period_counts": { "create": 3, "with_context": 1, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 1, "utility": 1 },
  "total_pages": { "create": 31, "with_context": 9, "standard_fill": 6, "verify": 4, "read": 2, "package": 0, "send_fax": 4, "utility": 8 },
  "period_pages": { "create": 7, "with_context": 2, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 2, "utility": 2 },
  "total_ctx_tokens": { "create": 0, "with_context": 18420, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 },
  "period_ctx_tokens": { "create": 0, "with_context": 4110, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 },
  "total_context_pages": { "create": 0, "with_context": 11, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 },
  "period_context_pages": { "create": 0, "with_context": 3, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 }
}
```

### Status codes

| Code | Meaning |
| --- | --- |
| 200 | The usage breakdown. |
| 401 | Missing or invalid API key. |

## Quote

```
POST /forms/quote
```

Authentication: Bearer API key required.

Price every route for this document and say whether the free tier covers it. Free and stateless; it counts as one call toward the hourly rate limit. The sample shows the shape; the amounts follow the live price list.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| file | body | file (multipart) | yes | The flat PDF to price. |
| context | body | file (multipart, repeatable) | no | Optional. Zero or more supporting documents, priced as with-context input. Repeat the field to attach more than one. |

```curl
curl -X POST https://api.getemboss.ai/forms/quote \
  -H "Authorization: Bearer sk_..." \
  -F "file=@application.pdf" \
  -F "context=@customer.json"
```

```js
const body = new FormData();
body.append("file", fileBlob, "application.pdf");
body.append("context", contextBlob, "customer.json");

const res = await fetch("https://api.getemboss.ai/forms/quote", {
  method: "POST",
  headers: { Authorization: "Bearer sk_..." },
  body,
});
const quote = await res.json();
```

```python
import requests

res = requests.post(
    "https://api.getemboss.ai/forms/quote",
    headers={"Authorization": "Bearer sk_..."},
    files={
        "file": open("application.pdf", "rb"),
        "context": open("customer.json", "rb"),
    },
)
quote = res.json()
```

### Response

```json
{
  "pages": 3,
  "context_pages": 1,
  "already_fillable": false,
  "effective": "2026-09-07",
  "billing": { "has_card": false, "exempt": false, "billing_url": "https://getemboss.ai/dashboard/billing" },
  "lines": {
    "create_form": { "cents": 5, "free": true,
      "kinds": { "create": { "covered": true, "reason": "within_allowance", "remaining": 4 } } },
    "create_and_fill_from_context": { "cents": 8, "free": false,
      "kinds": { "create": { "covered": true, "reason": "within_allowance", "remaining": 4 },
                 "with_context": { "covered": false, "reason": "allowance_used", "remaining": 0 } } },
    "fill_from_data": { "cents": 2, "free": true,
      "kinds": { "standard_fill": { "covered": true, "reason": "within_allowance", "remaining": 4 } } },
    "verify": { "cents": 1, "free": true,
      "kinds": { "verify": { "covered": true, "reason": "within_allowance", "remaining": 4 } } }
  }
}
```

### Status codes

| Code | Meaning |
| --- | --- |
| 200 | The price and free-tier verdict for every route. |
| 400 | Not a PDF. |
| 401 | Missing or invalid API key. |
| 413 | Too many pages or too much context. |
| 422 | Missing required file. Also pdf_unsafe: the PDF's form fields are built in a way that could compromise the service. Refused before any price, charge or stored file; the problem document's detail is "Emboss does not process PDF files that could compromise the service." and its code is pdf_unsafe. |

## Health

```
GET /health
```

Liveness probe. No authentication required.

```curl
curl https://api.getemboss.ai/health
```

```js
const res = await fetch("https://api.getemboss.ai/health");
const health = await res.json();
```

```python
import requests

res = requests.get("https://api.getemboss.ai/health")
health = res.json()
```

### Response

```json
{
  "status": "ok"
}
```

### Status codes

| Code | Meaning |
| --- | --- |
| 200 | Service is healthy. |

## See also

- [Tracking jobs](https://getemboss.ai/docs/tracking-jobs)
- [Bulk-fill PDFs programmatically](https://getemboss.ai/use-cases/bulk-fill-pdfs)