get__credits_stats_monthly

GET /credits/stats/monthly

Get Monthly Credit Statistics

Returns aggregated credit statistics by month for the authenticated user's organization. Each month includes consumption (credits used), purchases (pack buys), grants (subscription allocations), and net balance change. Useful for histograms and usage-over-time views.

TypeScript Client Library

public getCreditsMonthlyStats = async (query?: GetCreditsMonthlyStatsRequest): Promise<GetCreditsMonthlyStatsResponse> => {
  return this.makeRequest<GetCreditsMonthlyStatsResponse>('credits/stats/monthly', 'GET', query ?? null);
};

Code Samples

Shell

# Optional: number of months (default 12, max 24)
curl -X GET 'https://backend.flashback.tech/credits/stats/monthly?months=12' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

HTTP

JavaScript

Python

Example responses

200 Response

{
  "success": true,
  "data": [
    {
      "month": "2025-02-01T00:00:00.000Z",
      "consumption": 120,
      "purchases": 0,
      "grants": 500,
      "balance": 380
    },
    {
      "month": "2025-03-01T00:00:00.000Z",
      "consumption": 85,
      "purchases": 1100,
      "grants": 0,
      "balance": 1015
    }
  ],
  "totals": {
    "consumption": 205,
    "purchases": 1100,
    "grants": 500,
    "balance": 1395
  }
}

400 Response

{
  "success": false,
  "error_code": "CREDITS_NOT_ENABLED",
  "message": "Credits system is not enabled"
}

500 Response

{
  "success": false,
  "error_code": "INTERNAL_ERROR",
  "message": "Failed to retrieve monthly credit stats"
}

Query Parameters

Name	Type	Required	Description
» months	integer	false	Number of months to return (default: 12, max: 24). Months are from the start of the range to the current month.

Responses

Status	Meaning	Description	Schema
200	OK	Monthly stats and totals	Inline
400	Bad Request	Credits not enabled or no organization	Inline
404	Not Found	User not found	Inline
500	Internal Server Error	Server error	Inline

Response Schema (200)

Name	Type	Required	Description
» success	boolean	false	Whether the request succeeded
» data	array	false	One entry per month, ordered by month ascending
»» month	string (date-time)	false	First day of the month (ISO 8601)
»» consumption	number	false	Credits consumed that month (positive value for display)
»» purchases	number	false	Credits from pack purchases that month
»» grants	number	false	Credits from subscription grants that month
»» balance	number	false	Net change: grants + purchases − consumption
» totals	object	false	Sums over all returned months
»» consumption	number	false	Total consumption
»» purchases	number	false	Total purchases
»» grants	number	false	Total grants
»» balance	number	false	Total net balance change
» error_code	string	false	Set on error
» message	string	false	Error or status message

Security

• BearerAuth: Bearer token required.

• Organization: Results are scoped to the user's organization.

Notes

• Use this endpoint to build usage histograms (e.g. consumption, purchases/grants, and balance bars per month). The balance value per month is the net change for that month, not a running balance.

• Months with no activity will still appear in data with zero values. The date range is from (current month − months + 1) through the current month.