Pagination & Filtering

All list endpoints support pagination and filtering to efficiently retrieve data.

Pagination

Parameters

Parameter	Type	Default	Description
page	number	1	Page number (1-indexed)
limit	number	100	Items per page

Maximum limit: 500 items per page

Response Format

Every list response includes a page_context object:

{
  "data": [...],
  "page_context": {
    "count": 25,
    "page": 1,
    "per_page": 100,
    "total": 250,
    "has_more": true
  }
}

Field	Description
count	Number of items in current page
page	Current page number
per_page	Items per page
total	Total items across all pages
has_more	Whether more pages exist

Example: Iterating Through Pages

async function getAllTransactions() {
  const all_transactions = [];
  let page = 1;
  let has_more = true;

  while (has_more) {
    const response = await fetch(
      `https://statements.finopsbricks.com/api/v1/transactions?page=${page}&limit=100`,
      { headers: { 'api-key': KEY, 'api-secret': SECRET } }
    );
    const data = await response.json();

    all_transactions.push(...data.data);
    has_more = data.page_context.has_more;
    page++;
  }

  return all_transactions;
}

Field Selection

Use the fields parameter to request only specific fields, reducing response size.

Usage

GET /api/v1/transactions?fields=id,date,inflow,outflow

Example Response

{
  "data": [
    {
      "id": "abc123",
      "date": "2025-01-05",
      "inflow": 1000.50,
      "outflow": 0
    }
  ],
  "page_context": { ... }
}

Available Fields

Transactions: id, date, particulars, inflow, outflow, balance, entity, category, po, comments, type, account_id, account_name, statement

Accounts: id, name, category, description, acc_no, currency, color, opening_balance, is_archived, upload_frequency, created_at

Rules: id, name, description, priority, conditions, actions, enabled, created_at

Filtering

Different endpoints support different filter parameters.

Transactions Filters

Parameter	Type	Description
date_from	string	Transactions on or after date (YYYY-MM-DD)
date_to	string	Transactions on or before date (YYYY-MM-DD)
account	string	Filter by account ID
category	string	Filter by category (use "empty" for uncategorized)
entity	string	Filter by entity (use "empty" for no entity)
particulars	string	Search in particulars (case-insensitive)
type	string	Filter by transaction type
comments	string	Search in comments (use "empty" for no comments)

Example: Filter by Date Range

curl "https://statements.finopsbricks.com/api/v1/transactions?date_from=2025-01-01&date_to=2025-01-31" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Accounts Filters

Parameter	Type	Description
is_archived	boolean	Filter by archived status
category	string	Filter by type (bank, credit_card)

Rules Filters

Parameter	Type	Description
enabled	boolean	Filter by enabled status

Sorting

Parameters

Parameter	Type	Default	Description
sort_order	string	DESC	Sort direction (ASC or DESC)

Transactions are sorted by date, then by created_at.

Example

# Get oldest transactions first
curl "https://statements.finopsbricks.com/api/v1/transactions?sort_order=ASC" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Combining Parameters

All parameters can be combined:

curl "https://statements.finopsbricks.com/api/v1/transactions?\
page=1&\
limit=50&\
fields=id,date,particulars,inflow,outflow&\
date_from=2025-01-01&\
category=income&\
sort_order=DESC" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"