Skip to main content

​
Endpoint

GET /api/v1/groups
Retrieve all category groups for the authenticated user with optional monthly budget totals and category counts.

​
Query parameters

​
q
string
Search groups by name using case-insensitive pattern matching
​
ids
string
Comma-separated list of group UUIDs to filter by
​
include_category_count
boolean
default:"false"
Include the count of categories in each group. Accepts true, false, 1, or 0
​
include_budget_totals
boolean
default:"false"
Include monthly budget totals (assigned, spent, rollover, budget left) for the group. Accepts true, false, 1, or 0
​
month
string
Month for budget totals in YYYY-MM format. Defaults to current month when include_budget_totals=true
​
fields
string
Comma-separated list of fields to return. Available fields: id, name, created_at, category_count, month, month_assigned, month_spent, month_rollover, month_budget_left
​
sort
string
default:"name"
Field to sort by. Options: name, created_at
​
order
string
default:"asc"
Sort order. Options: asc, desc
​
limit
integer
default:"100"
Maximum number of results to return (1-1000)
​
offset
integer
default:"0"
Number of results to skip for pagination
​
cursor
string
Cursor for pagination. Cannot be used with offset

​
Response fields

​
data
array
Array of group objects
​
id
string
Unique group identifier (UUID)
​
name
string
Group name
​
created_at
string
Group creation timestamp (ISO 8601)
​
category_count
integer
Number of categories in this group (only included when include_category_count=true)
​
month
string
Month for budget totals in YYYY-MM format (only included when include_budget_totals=true)
​
month_assigned
number
Total amount assigned to categories in this group for the month (only included when include_budget_totals=true)
​
month_spent
number
Total amount spent across categories in this group for the month (only included when include_budget_totals=true)
​
month_rollover
number
Total rollover amount for categories in this group (only included when include_budget_totals=true)
​
month_budget_left
number
Total budget remaining for this group (assigned + rollover - spent) (only included when include_budget_totals=true)
​
meta
object
Pagination and metadata
​
total
integer
Total number of matching groups
​
returned
integer
Number of groups returned in this response
​
limit
integer
Maximum results per page
​
offset
integer
Current offset
​
next_cursor
string | null
Cursor for the next page, or null if no more results
​
sort
string
Field used for sorting
​
order
string
Sort order applied
​
include_category_count
boolean
Whether category counts were included
​
include_budget_totals
boolean
Whether budget totals were included
​
month
string | null
Month used for budget totals

​
Example request

curl -X GET "https://api.cashcat.app/api/v1/groups?include_category_count=true&include_budget_totals=true&month=2024-03" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

{
  "data": [
    {
      "id": "g1h2i3j4-k5l6-7890-ghij-234567890123",
      "name": "Essential Expenses",
      "created_at": "2024-01-01T12:00:00Z",
      "category_count": 5,
      "month": "2024-03",
      "month_assigned": 1500.00,
      "month_spent": 1200.50,
      "month_rollover": 100.00,
      "month_budget_left": 399.50
    },
    {
      "id": "h2i3j4k5-l6m7-8901-hijk-345678901234",
      "name": "Discretionary",
      "created_at": "2024-01-02T10:00:00Z",
      "category_count": 3,
      "month": "2024-03",
      "month_assigned": 500.00,
      "month_spent": 450.75,
      "month_rollover": 50.00,
      "month_budget_left": 99.25
    }
  ],
  "meta": {
    "total": 2,
    "returned": 2,
    "limit": 100,
    "offset": 0,
    "next_cursor": null,
    "sort": "name",
    "order": "asc",
    "include_category_count": true,
    "include_budget_totals": true,
    "month": "2024-03"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us