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.

import SpaceInvoices from '@spaceinvoices/js-sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.entityStats.queryEntityStats([
  {
    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"
    ]
  }
]);

console.log(response);

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: