Entity Stats

Flexible aggregation queries for entity data. Query counts, sums, averages across invoices, payments, customers, and more.

Query entity stats (batch)

POST/stats/query

Execute one or more aggregation queries on entity data in a single request.

Send an array of 1-25 queries. Each query runs independently and results are returned in the same order.

Available tables: invoices, estimates, credit_notes, advance_invoices, payments, customers, items

Metric types: count, sum, avg, min, max

Virtual fields for group_by:
- month - Extract month from date (YYYY-MM)
- year - Extract year from date (YYYY)
- overdue_bucket - Invoice aging bucket (current, 1-30, 31-60, 61-90, 90+)

Example — single query (monthly revenue):
``json [{ "metrics": [{ "type": "sum", "field": "total_with_tax", "alias": "revenue" }], "table": "invoices", "date_from": "2024-01-01", "filters": { "is_draft": false, "voided_at": null }, "group_by": ["month"] }]`Example — multi query (dashboard counts):`json [ { "metrics": [{ "type": "count", "alias": "total" }], "table": "invoices" }, { "metrics": [{ "type": "count", "alias": "total" }], "table": "customers" } ]``

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

curl -X POST "https://eu.spaceinvoices.com/stats/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "metrics": [
        {
          "type": "sum",
          "field": "total_with_tax",
          "alias": "revenue"
        }
      ],
      "table": "invoices",
      "date_from": "2024-01-01",
      "filters": {
        "is_draft": false,
        "voided_at": null
      },
      "group_by": [
        "month"
      ]
    }
  ]'

Example:

Response

json

[
  {
    "query": {
      "table": "invoices",
      "date_from": "2024-01-01",
      "date_to": null,
      "group_by": [
        "month"
      ]
    },
    "data": [
      {
        "month": "2024-01",
        "revenue": 5000
      },
      {
        "month": "2024-02",
        "revenue": 7500
      }
    ],
    "row_count": 2
  }
]

Example: