Developers
Expense tracker API
The Traackly REST API: base URL, API keys and authentication, endpoints, the expense object, pagination, rate limits and errors. Included on Scale.
The Traackly API is a REST API that returns JSON. Use it to read, add, update and delete your expenses, and to read your categories and account. It is included on the Scale plan. The current version is v1.
Base URL: https://traackly.com/api/v1
Authentication
- Sign in to Traackly on the Scale plan.
- Open Settings, then API Keys, and click Create Key.
- Choose Read Only or Read & Write, and copy the key. It is shown only once.
Keys start with et_sk_. Send the key as a Bearer token on every request:
curl https://traackly.com/api/v1/me \ -H "Authorization: Bearer et_sk_your_api_key"
A key only reaches the workspace it was created in. You can have up to 3 active keys and revoke any of them at any time. Keep keys on your server, never in browser code or a public repository.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /me | Your account: name, email, plan |
| GET | /expenses | List expenses, newest first, with pagination |
| POST | /expenses | Create an expense. Returns 201 |
| GET | /expenses/{id} | Get one expense |
| PATCH | /expenses/{id} | Update an expense. Send only the fields to change. An unchanged stored amount may be sent back as read |
| DELETE | /expenses/{id} | Delete an expense. Returns 204 |
| GET | /categories | List your categories, built-in and custom |
All paths are relative to the base URL. Read Only keys can call the GET endpoints only.
The expense object
| Field | Type | Description |
|---|---|---|
id | uuid | Unique ID |
amount | number | Positive. New amounts use at most the currency's decimals (0, 2 or 3, per ISO 4217, e.g. 3 for KWD). A scanned receipt keeps the decimals printed on it, up to 3 |
currency | string | 3-letter ISO 4217 code, such as USD |
merchant | string | Where the money was spent |
date | string | YYYY-MM-DD |
description | string | Optional note. Empty when not set (may be null on older expenses) |
category_id | uuid | A category ID from GET /categories |
source | string | manual, scan, quick_add, voice, email, recurring or api |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Create an expense
Required fields: merchant, amount (a JSON number), currency, date and category_id. Optional: description. Send the body as JSON with Content-Type: application/json.
curl -X POST https://traackly.com/api/v1/expenses \
-H "Authorization: Bearer et_sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"merchant": "Cloud Hosting",
"amount": 18.40,
"currency": "USD",
"date": "2026-10-08",
"category_id": "a category id from GET /categories"
}'The response is 201 Created with the new expense in data, and its source is api.
Pagination
GET /expenses returns up to 50 expenses per page. Set limit (1 to 100) to change that. The response has a meta object:
{
"data": [],
"meta": { "has_more": true, "next_cursor": "eyJkYXRl...", "api_version": "v1" }
}While has_more is true, request the next page with ?cursor= set to next_cursor.
Rate limits
60 requests a minute per key, and 180 a minute across all your keys. Over the limit, the API answers 429 with a Retry-After header in seconds.
Errors
Every error has the same shape:
{
"error": {
"code": "validation_error",
"status": 422,
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"fields": [{ "field": "amount", "message": "Must be positive" }]
}
}| Status | Meaning |
|---|---|
400 | Malformed request, such as invalid JSON or a missing Content-Type |
401 | Missing or invalid API key (also after you leave Scale, because your keys are revoked) |
402 | Your subscription payment is outstanding, so API access is paused |
403 | Your plan does not include the API, or a Read Only key tried to write |
404 | The expense or path does not exist |
422 | Invalid fields, listed in fields |
429 | Rate limit reached. Wait for Retry-After seconds |
Quote the request_id when you contact support.
Full reference
Scale accounts get the complete API reference in the app, under Settings, API Keys, View API Documentation: every filter and sort option, idempotency keys for safe retries, and all error codes.