Entity Stats

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

Query entity stats

POST/stats/query

Execute a flexible aggregation query on entity data.

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 - 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 - Top customers:`json { "metrics": [ { "type": "sum", "field": "total_with_tax", "alias": "revenue" }, { "type": "count", "alias": "invoice_count" } ], "table": "invoices", "filters": { "is_draft": false, "voided_at": null }, "group_by": ["customer_id"], "order_by": [{ "field": "revenue", "direction": "desc" }], "limit": 5 }``

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Body parameters

metricsarray of objectsrequired

Metrics to compute

tablestringrequired

Table to query

Possible values: "invoices", "estimates", "credit_notes", "advance_invoices", "payments", "customers", "items", "invoice_taxes"

Other parameters

date_fromstringoptional

date_tostringoptional

filtersobjectoptional

group_byarray of stringsoptional

order_byarray of objectsoptional

limitintegeroptional

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"
    ]
  }'

Response

Returns

dataarray of objects

Query results - shape depends on metrics and group_by

Other parameters

queryobject

row_countinteger

json

{
  "data": [
    {
      "month": "2024-01",
      "revenue": 5000
    },
    {
      "month": "2024-02",
      "revenue": 7500
    }
  ]
}