Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

fix(api): fetch byApiKey historical usage in cached 7-day slices (#4731)

Gergő Móricz94efff4d1414
diff --git a/apps/api/src/__tests__/snips/v2/billing.test.ts b/apps/api/src/__tests__/snips/v2/billing.test.ts
index 7bc6a8e9d..dd6a79773 100644
--- a/apps/api/src/__tests__/snips/v2/billing.test.ts
+++ b/apps/api/src/__tests__/snips/v2/billing.test.ts
@@ -694,6 +694,35 @@ describeIf(TEST_PRODUCTION)("Billing tests", () => {
60000,
);
+ it.concurrent(
+ "returns historical credit usage by API key",
+ async () => {
+ const identity = await idmux({
+ name: "billing/returns historical credit usage by API key",
+ credits: 100,
+ });
+
+ const result = await creditUsageHistorical(identity, { byApiKey: true });
+
+ expect(result.success).toBe(true);
+ expect(Array.isArray(result.periods)).toBe(true);
+
+ for (const period of result.periods) {
+ expect(typeof period.apiKey).toBe("string");
+ expect(typeof period.creditsUsed).toBe("number");
+ expect(period.creditsUsed).toBeGreaterThanOrEqual(0);
+ expect(Number.isNaN(Date.parse(period.startDate ?? ""))).toBe(false);
+ }
+
+ for (let i = 1; i < result.periods.length; i++) {
+ expect(Date.parse(result.periods[i].startDate!)).toBeGreaterThanOrEqual(
+ Date.parse(result.periods[i - 1].startDate!),
+ );
+ }
+ },
+ 60000,
+ );
+
it.concurrent(
"returns historical token usage",
async () => {
diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.ts
index 32ad050b1..cba7dfef7 100644
--- a/apps/api/src/__tests__/snips/v2/lib.ts
+++ b/apps/api/src/__tests__/snips/v2/lib.ts
@@ -871,16 +871,21 @@ export async function creditUsage(
return req.body.data;
}
-export async function creditUsageHistorical(identity: Identity): Promise<{
+export async function creditUsageHistorical(
+ identity: Identity,
+ options: { byApiKey?: boolean } = {},
+): Promise<{
success: boolean;
periods: {
startDate: string | null;
endDate: string | null;
+ apiKey?: string;
creditsUsed: number;
}[];
}> {
const req = await request(TEST_API_URL)
.get("/v2/team/credit-usage/historical")
+ .query(options.byApiKey ? { byApiKey: "true" } : {})
.set("Authorization", `Bearer ${identity.apiKey}`)
.set("Content-Type", "application/json");
diff --git a/apps/api/src/services/autumn/__tests__/usage.test.ts b/apps/api/src/services/autumn/__tests__/usage.test.ts
index 2c47da609..a08882ce4 100644
--- a/apps/api/src/services/autumn/__tests__/usage.test.ts
+++ b/apps/api/src/services/autumn/__tests__/usage.test.ts
@@ -24,12 +24,23 @@ let teamLookup = {
let apiKeysData: Array<{ id: number; name: string }> = [];
+const redisStore = new Map<string, string>();
+const mockGetValue = vi.fn<(key: string) => Promise<string | null>>();
+const mockSetValue =
+ vi.fn<(key: string, value: string, expire?: number) => Promise<void>>();
+
vi.mock("../client", () => ({
get autumnClient() {
return autumnClientRef;
},
}));
+vi.mock("../../redis", () => ({
+ getValue: (key: string) => mockGetValue(key),
+ setValue: (key: string, value: string, expire?: number) =>
+ mockSetValue(key, value, expire),
+}));
+
vi.mock("../../../db/connection", () => ({
get dbRr() {
return {
@@ -64,6 +75,11 @@ beforeEach(() => {
};
teamLookup = { data: { org_id: "org-1" }, error: null };
apiKeysData = [];
+ redisStore.clear();
+ mockGetValue.mockImplementation(async key => redisStore.get(key) ?? null);
+ mockSetValue.mockImplementation(async (key, value) => {
+ redisStore.set(key, value);
+ });
});
// ---------------------------------------------------------------------------
@@ -846,29 +862,57 @@ describe("getTeamHistoricalUsage", () => {
});
});
+// The byApiKey breakdown asks Autumn for fixed 7-day slices. At this instant
+// the 90-day window starts 2026-01-20T00:00Z; the epoch-aligned slices run
+// from 2026-01-15 to 2026-04-23, fourteen of them, and the one holding today
+// is 2026-04-16..2026-04-23.
+const BY_API_KEY_NOW = "2026-04-20T12:00:00.000Z";
+const BY_API_KEY_SLICE_COUNT = 14;
+const CURRENT_SLICE_START = Date.parse("2026-04-16T00:00:00.000Z");
+
+/**
+ * Stands in for Autumn's grouped aggregate: answers each call with the days
+ * inside its `customRange`. The end is inclusive, so a bin that sits exactly
+ * on a slice boundary comes back from both neighbouring slices.
+ */
+function autumnServesDays(
+ days: Array<{ day: string; credits: Record<string, number> }>,
+) {
+ mockAggregate.mockImplementation(async (args: any) => ({
+ list: days
+ .map(d => ({
+ period: Date.parse(d.day),
+ grouped_values: { CREDITS: d.credits },
+ }))
+ .filter(
+ entry =>
+ entry.period >= args.customRange.start &&
+ entry.period <= args.customRange.end,
+ ),
+ }));
+}
+
describe("getTeamHistoricalUsageByApiKey", () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ["Date"] });
+ vi.setSystemTime(new Date(BY_API_KEY_NOW));
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
it("aggregates daily grouped usage into calendar-month buckets", async () => {
apiKeysData = [
{ id: 101, name: "Default" },
{ id: 202, name: "postman" },
];
- mockAggregate.mockResolvedValue({
- list: [
- {
- period: Date.parse("2026-03-30T00:00:00.000Z"),
- grouped_values: { CREDITS: { "101": 10, "202": 3 } },
- },
- {
- period: Date.parse("2026-03-31T00:00:00.000Z"),
- grouped_values: { CREDITS: { "101": 26 } },
- },
- {
- period: Date.parse("2026-04-02T00:00:00.000Z"),
- grouped_values: { CREDITS: { "202": 5 } },
- },
- ],
- });
+ autumnServesDays([
+ { day: "2026-03-30T00:00:00.000Z", credits: { "101": 10, "202": 3 } },
+ { day: "2026-03-31T00:00:00.000Z", credits: { "101": 26 } },
+ { day: "2026-04-02T00:00:00.000Z", credits: { "202": 5 } },
+ ]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
@@ -890,36 +934,210 @@ describe("getTeamHistoricalUsageByApiKey", () => {
creditsUsed: 5,
},
]);
+ });
- expect(mockAggregate).toHaveBeenCalledWith(
- expect.objectContaining({
- customerId: "org-1",
- entityId: "team-1",
- featureId: "CREDITS",
- range: "90d",
- binSize: "day",
- groupBy: "properties.apiKeyId",
- }),
- expect.objectContaining({ timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS }),
+ it("asks Autumn for 7-day slices across the window, today's slice first", async () => {
+ autumnServesDays([]);
+
+ await getTeamHistoricalUsageByApiKey("team-1");
+
+ expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
+
+ const [firstArgs] = mockAggregate.mock.calls[0];
+ expect(firstArgs.customRange).toEqual({
+ start: CURRENT_SLICE_START,
+ end: Date.parse(BY_API_KEY_NOW),
+ });
+
+ for (const [args, options] of mockAggregate.mock.calls) {
+ expect(args).toEqual(
+ expect.objectContaining({
+ customerId: "org-1",
+ entityId: "team-1",
+ featureId: "CREDITS",
+ binSize: "day",
+ groupBy: "properties.apiKeyId",
+ maxGroups: 250,
+ }),
+ );
+ expect(args.range).toBeUndefined();
+ expect(options).toEqual(
+ expect.objectContaining({
+ timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS,
+ retryCodes: ["429"],
+ }),
+ );
+ }
+
+ // The slices tile the window with no gap and no overlap.
+ const ranges = mockAggregate.mock.calls
+ .map(([args]) => args.customRange)
+ .sort((a, b) => a.start - b.start);
+ expect(ranges[0].start).toBe(Date.parse("2026-01-15T00:00:00.000Z"));
+ for (let i = 1; i < ranges.length; i++) {
+ expect(ranges[i].start).toBe(ranges[i - 1].end);
+ expect(ranges[i - 1].end - ranges[i - 1].start).toBe(7 * 86_400_000);
+ }
+ });
+
+ it("counts a day on a slice boundary once, though both slices return it", async () => {
+ apiKeysData = [{ id: 101, name: "Default" }];
+
+ // 2026-03-26 is where one slice ends and the next begins.
+ autumnServesDays([
+ { day: "2026-03-26T00:00:00.000Z", credits: { "101": 5 } },
+ ]);
+
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
+ {
+ startDate: "2026-03-01T00:00:00.000Z",
+ endDate: null,
+ apiKey: "Default",
+ creditsUsed: 5,
+ },
+ ]);
+ });
+
+ it("leaves out days before the window that the oldest slice returns", async () => {
+ apiKeysData = [{ id: 101, name: "Default" }];
+
+ autumnServesDays([
+ { day: "2026-01-16T00:00:00.000Z", credits: { "101": 1000 } },
+ { day: "2026-01-20T00:00:00.000Z", credits: { "101": 4 } },
+ ]);
+
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
+ {
+ startDate: "2026-01-01T00:00:00.000Z",
+ endDate: null,
+ apiKey: "Default",
+ creditsUsed: 4,
+ },
+ ]);
+ });
+
+ it("serves settled slices from the cache on the next request", async () => {
+ apiKeysData = [{ id: 101, name: "Default" }];
+ autumnServesDays([
+ { day: "2026-02-10T00:00:00.000Z", credits: { "101": 7 } },
+ { day: "2026-04-17T00:00:00.000Z", credits: { "101": 2 } },
+ ]);
+
+ const first = await getTeamHistoricalUsageByApiKey("team-1");
+ expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
+ expect(mockSetValue).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT - 1);
+ for (const [key, , expire] of mockSetValue.mock.calls) {
+ expect(key).toMatch(/^historical-usage-by-api-key:v1:team-1:\d+$/);
+ expect(key).not.toContain(String(CURRENT_SLICE_START));
+ // Settled at least a day after it ends, a slice leaves the window at
+ // most ~91 days after it ends, so a 90-day TTL outlives its use.
+ expect(expire).toBe(90 * 24 * 60 * 60);
+ }
+
+ mockAggregate.mockClear();
+ const second = await getTeamHistoricalUsageByApiKey("team-1");
+
+ expect(second).toEqual(first);
+ expect(mockAggregate).toHaveBeenCalledTimes(1);
+ expect(mockAggregate.mock.calls[0][0].customRange.start).toBe(
+ CURRENT_SLICE_START,
+ );
+ });
+
+ it("keeps asking Autumn for a slice that ended less than a day ago", async () => {
+ // Ten hours into the 2026-04-16 slice: the 2026-04-09 slice has ended but
+ // has not settled yet.
+ vi.setSystemTime(new Date("2026-04-16T10:00:00.000Z"));
+ const previousSliceStart = Date.parse("2026-04-09T00:00:00.000Z");
+ autumnServesDays([]);
+
+ await getTeamHistoricalUsageByApiKey("team-1");
+ expect(
+ mockSetValue.mock.calls.some(([key]) =>
+ key.endsWith(`:${previousSliceStart}`),
+ ),
+ ).toBe(false);
+
+ mockAggregate.mockClear();
+ await getTeamHistoricalUsageByApiKey("team-1");
+
+ expect(
+ mockAggregate.mock.calls.map(([args]) => args.customRange.start).sort(),
+ ).toEqual([previousSliceStart, CURRENT_SLICE_START]);
+ });
+
+ it("asks Autumn again for a slice whose cache entry is malformed", async () => {
+ apiKeysData = [{ id: 101, name: "Default" }];
+ autumnServesDays([
+ { day: "2026-02-10T00:00:00.000Z", credits: { "101": 7 } },
+ ]);
+ mockGetValue.mockResolvedValue(JSON.stringify([{ period: "yesterday" }]));
+
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
+ {
+ startDate: "2026-02-01T00:00:00.000Z",
+ endDate: null,
+ apiKey: "Default",
+ creditsUsed: 7,
+ },
+ ]);
+ expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
+ });
+
+ it("answers from Autumn when the cache cannot be read or written", async () => {
+ apiKeysData = [{ id: 101, name: "Default" }];
+ autumnServesDays([
+ { day: "2026-02-10T00:00:00.000Z", credits: { "101": 7 } },
+ ]);
+ mockGetValue.mockRejectedValue(new Error("redis down"));
+ mockSetValue.mockRejectedValue(new Error("redis down"));
+
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
+ {
+ startDate: "2026-02-01T00:00:00.000Z",
+ endDate: null,
+ apiKey: "Default",
+ creditsUsed: 7,
+ },
+ ]);
+ });
+
+ it("fails the request when a slice fails, without starting further slices", async () => {
+ mockAggregate.mockImplementation(async (args: any) => {
+ if (args.customRange.start === Date.parse("2026-01-15T00:00:00.000Z")) {
+ throw Object.assign(new Error("gateway timeout"), { statusCode: 504 });
+ }
+ return { list: [] };
+ });
+
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).rejects.toThrow(
+ "gateway timeout",
+ );
+ // Today's slice, the failing oldest slice, and the one other slice that
+ // was already in flight beside it.
+ expect(mockAggregate.mock.calls.length).toBeLessThanOrEqual(3);
+ });
+
+ it("rethrows a non-404 error from today's slice", async () => {
+ mockAggregate.mockRejectedValueOnce(
+ Object.assign(new Error("boom"), { statusCode: 500 }),
);
+
+ await expect(getTeamHistoricalUsageByApiKey("team-1")).rejects.toThrow(
+ "boom",
+ );
+ expect(mockAggregate).toHaveBeenCalledTimes(1);
});
it("labels unresolvable apiKeyIds as 'Unknown' instead of echoing raw values", async () => {
apiKeysData = [];
- mockAggregate.mockResolvedValue({
- list: [
- {
- period: Date.parse("2026-04-15T00:00:00.000Z"),
- grouped_values: {
- CREDITS: {
- ba9045fffbd34fc8aabc2597df6ba044: 11,
- "99999999": 7,
- },
- },
- },
- ],
- });
+ autumnServesDays([
+ {
+ day: "2026-04-15T00:00:00.000Z",
+ credits: { ba9045fffbd34fc8aabc2597df6ba044: 11, "99999999": 7 },
+ },
+ ]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
@@ -934,18 +1152,10 @@ describe("getTeamHistoricalUsageByApiKey", () => {
it("uses the next calendar month as endDate for grouped data when a month has zero usage", async () => {
apiKeysData = [{ id: 101, name: "Default" }];
- mockAggregate.mockResolvedValue({
- list: [
- {
- period: Date.parse("2026-01-31T00:00:00.000Z"),
- grouped_values: { CREDITS: { "101": 12 } },
- },
- {
- period: Date.parse("2026-03-01T00:00:00.000Z"),
- grouped_values: { CREDITS: { "101": 7 } },
- },
- ],
- });
+ autumnServesDays([
+ { day: "2026-01-31T00:00:00.000Z", credits: { "101": 12 } },
+ { day: "2026-03-01T00:00:00.000Z", credits: { "101": 7 } },
+ ]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
@@ -970,6 +1180,7 @@ describe("getTeamHistoricalUsageByApiKey", () => {
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([]);
+ // Only today's entity-scoped slice is asked for; no customer-level retry.
expect(mockAggregate).toHaveBeenCalledTimes(1);
expect(mockAggregate).toHaveBeenNthCalledWith(
1,
@@ -977,6 +1188,10 @@ describe("getTeamHistoricalUsageByApiKey", () => {
customerId: "org-1",
entityId: "team-1",
groupBy: "properties.apiKeyId",
+ customRange: {
+ start: CURRENT_SLICE_START,
+ end: Date.parse(BY_API_KEY_NOW),
+ },
}),
expect.objectContaining({ timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS }),
);
@@ -1003,14 +1218,15 @@ describe("historical usage Autumn timeout override", () => {
expect(options).toEqual({ timeoutMs: 15000 });
});
- it("passes a 15s per-call timeout for the grouped byApiKey aggregate", async () => {
+ it("passes a 15s per-call timeout for every grouped byApiKey slice", async () => {
mockAggregate.mockResolvedValue({ list: [] });
await getTeamHistoricalUsageByApiKey("team-1");
- expect(mockAggregate).toHaveBeenCalledTimes(1);
- const [, options] = mockAggregate.mock.calls[0];
- expect(options).toEqual({ timeoutMs: 15000 });
+ expect(mockAggregate.mock.calls.length).toBeGreaterThan(1);
+ for (const [, options] of mockAggregate.mock.calls) {
+ expect(options?.timeoutMs).toBe(15000);
+ }
});
it("overrides the Autumn client's global 2s timeout with a larger value", async () => {
@@ -1019,7 +1235,7 @@ describe("historical usage Autumn timeout override", () => {
await getTeamHistoricalUsage("team-1");
await getTeamHistoricalUsageByApiKey("team-1");
- expect(mockAggregate).toHaveBeenCalledTimes(2);
+ expect(mockAggregate.mock.calls.length).toBeGreaterThan(2);
for (const [, options] of mockAggregate.mock.calls) {
expect(options?.timeoutMs).toBeGreaterThan(2000);
}
diff --git a/apps/api/src/services/autumn/usage.ts b/apps/api/src/services/autumn/usage.ts
index 42e1d08fa..eb0783ba2 100644
--- a/apps/api/src/services/autumn/usage.ts
+++ b/apps/api/src/services/autumn/usage.ts
@@ -2,12 +2,15 @@ import { logger } from "../../lib/logger";
import { eq, inArray } from "drizzle-orm";
import { dbRr } from "../../db/connection";
import * as schema from "../../db/schema";
+import { getValue, setValue } from "../redis";
import { autumnClient } from "./client";
import { CREDITS_FEATURE_ID } from "./autumn.service";
export const TOKENS_PER_CREDIT = 15;
const HISTORICAL_RANGE = "90d";
const HISTORICAL_BIN_SIZE = "day";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HISTORICAL_WINDOW_MS = 90 * DAY_MS;
// The historical/analytics aggregations below are bucketed by day (and
// optionally grouped by API key), so Autumn has to walk raw events and their
@@ -17,6 +20,38 @@ const HISTORICAL_BIN_SIZE = "day";
// tight here, so these calls override it per call.
const HISTORICAL_AGGREGATE_TIMEOUT_MS = 15000;
+// Grouping by API key over the whole 90-day window does not finish inside that
+// timeout for teams with tens of millions of events in it, so the byApiKey
+// breakdown asks Autumn for fixed 7-day slices instead. A slice that ended
+// over a day ago no longer changes and is cached for as long as it can still
+// fall inside the window, so a warm request only asks Autumn for the slice
+// holding today (and, for a day after a slice boundary, the one before it).
+const BY_API_KEY_SLICE_MS = 7 * DAY_MS;
+const BY_API_KEY_SLICE_SETTLE_MS = DAY_MS;
+const BY_API_KEY_SLICE_CACHE_TTL_SECONDS = HISTORICAL_WINDOW_MS / 1000;
+const BY_API_KEY_SLICE_CONCURRENCY = 2;
+
+// Autumn's maximum. Its default of 9 folds every further key into one "Other"
+// group per day, which the response can only label "Unknown".
+const BY_API_KEY_MAX_GROUPS = 250;
+
+// Autumn limits event aggregates per customer per second, and a cold byApiKey
+// request makes one call per slice. A rate-limited slice waits and retries;
+// every other status fails the request as before.
+const BY_API_KEY_RATE_LIMIT_RETRY = {
+ retries: {
+ strategy: "backoff" as const,
+ backoff: {
+ initialInterval: 250,
+ maxInterval: 1000,
+ exponent: 2,
+ maxElapsedTime: 3000,
+ },
+ retryConnectionErrors: false,
+ },
+ retryCodes: ["429"],
+};
+
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
@@ -131,23 +166,26 @@ function getGroupedCredits(entry: any): Record<string, number> | undefined {
);
}
+/** One day of credits used, keyed by the `apiKeyId` Autumn grouped on. */
+interface ApiKeyUsageDay {
+ period: number;
+ credits: Record<string, number>;
+}
+
async function aggregateHistoricalPeriodsByApiKeyMonth(
- list: any[],
+ days: ApiKeyUsageDay[],
): Promise<HistoricalPeriodByApiKey[]> {
const monthApiKeyTotals = new Map<string, Map<string, number>>();
const allApiKeyIds = new Set<string>();
- for (const entry of list) {
- const monthStart = toMonthStartIso(entry.period);
+ for (const day of days) {
+ const monthStart = toMonthStartIso(day.period);
if (!monthStart) continue;
- const grouped = getGroupedCredits(entry);
- if (!grouped) continue;
-
const monthTotals =
monthApiKeyTotals.get(monthStart) ?? new Map<string, number>();
- for (const [apiKeyId, creditsUsed] of Object.entries(grouped)) {
+ for (const [apiKeyId, creditsUsed] of Object.entries(day.credits)) {
allApiKeyIds.add(apiKeyId);
monthTotals.set(apiKeyId, (monthTotals.get(apiKeyId) ?? 0) + creditsUsed);
}
@@ -412,16 +450,169 @@ export async function getTeamHistoricalUsage(
return aggregateHistoricalPeriodsByMonth(response.list ?? []);
}
+interface UsageSlice {
+ start: number;
+ end: number;
+}
+
+/**
+ * The fixed 7-day slices covering `[windowStart, now]`, oldest first. They
+ * are aligned to the Unix epoch rather than to the window, so a slice keeps
+ * the same bounds (and cache key) while the window slides over it.
+ */
+function byApiKeySlices(windowStart: number, now: number): UsageSlice[] {
+ const slices: UsageSlice[] = [];
+ let start =
+ Math.floor(windowStart / BY_API_KEY_SLICE_MS) * BY_API_KEY_SLICE_MS;
+ for (; start <= now; start += BY_API_KEY_SLICE_MS) {
+ slices.push({ start, end: start + BY_API_KEY_SLICE_MS });
+ }
+ return slices;
+}
+
+function sliceCacheKey(teamId: string, slice: UsageSlice): string {
+ return `historical-usage-by-api-key:v1:${teamId}:${slice.start}`;
+}
+
+function isApiKeyUsageDays(value: unknown): value is ApiKeyUsageDay[] {
+ return (
+ Array.isArray(value) &&
+ value.every(
+ day =>
+ typeof day?.period === "number" &&
+ typeof day.credits === "object" &&
+ day.credits !== null &&
+ !Array.isArray(day.credits) &&
+ Object.values(day.credits).every(v => typeof v === "number"),
+ )
+ );
+}
+
+async function readCachedSlice(
+ teamId: string,
+ slice: UsageSlice,
+): Promise<ApiKeyUsageDay[] | null> {
+ try {
+ const cached = await getValue(sliceCacheKey(teamId, slice));
+ if (cached === null) return null;
+ const parsed = JSON.parse(cached);
+ if (isApiKeyUsageDays(parsed)) return parsed;
+ logger.warn("Ignoring malformed historical usage cache entry", {
+ teamId,
+ sliceStart: slice.start,
+ });
+ } catch (error) {
+ logger.warn("Failed to read historical usage cache", {
+ teamId,
+ sliceStart: slice.start,
+ error,
+ });
+ }
+ return null;
+}
+
+async function writeCachedSlice(
+ teamId: string,
+ slice: UsageSlice,
+ days: ApiKeyUsageDay[],
+): Promise<void> {
+ try {
+ await setValue(
+ sliceCacheKey(teamId, slice),
+ JSON.stringify(days),
+ BY_API_KEY_SLICE_CACHE_TTL_SECONDS,
+ );
+ } catch (error) {
+ logger.warn("Failed to cache historical usage slice", {
+ teamId,
+ sliceStart: slice.start,
+ error,
+ });
+ }
+}
+
+async function fetchApiKeyUsageSlice(
+ client: NonNullable<typeof autumnClient>,
+ orgId: string,
+ teamId: string,
+ slice: UsageSlice,
+ now: number,
+): Promise<ApiKeyUsageDay[]> {
+ const response: any = await client.events.aggregate(
+ {
+ customerId: orgId,
+ entityId: teamId,
+ featureId: CREDITS_FEATURE_ID,
+ customRange: { start: slice.start, end: Math.min(slice.end, now) },
+ binSize: HISTORICAL_BIN_SIZE,
+ groupBy: "properties.apiKeyId",
+ maxGroups: BY_API_KEY_MAX_GROUPS,
+ },
+ {
+ timeoutMs: HISTORICAL_AGGREGATE_TIMEOUT_MS,
+ ...BY_API_KEY_RATE_LIMIT_RETRY,
+ },
+ );
+
+ const days: ApiKeyUsageDay[] = [];
+ for (const entry of response?.list ?? []) {
+ const period = new Date(entry.period).getTime();
+ // A bin outside the slice belongs to its neighbour, which counts it.
+ if (!(period >= slice.start && period < slice.end)) continue;
+
+ const credits = getGroupedCredits(entry);
+ if (credits) days.push({ period, credits });
+ }
+ return days;
+}
+
+/**
+ * Runs `fn` over `items` with at most `limit` calls in flight, keeping the
+ * results in input order. After the first failure no further item is started,
+ * and that failure is what rejects.
+ */
+async function mapWithConcurrency<T, R>(
+ items: T[],
+ limit: number,
+ fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+ const results = new Array<R>(items.length);
+ let next = 0;
+ let failed = false;
+
+ const worker = async () => {
+ while (!failed && next < items.length) {
+ const index = next++;
+ try {
+ results[index] = await fn(items[index]);
+ } catch (error) {
+ failed = true;
+ throw error;
+ }
+ }
+ };
+
+ await Promise.all(
+ Array.from({ length: Math.min(limit, items.length) }, worker),
+ );
+ return results;
+}
+
/**
* Fetches a team's historical credit usage grouped by API key from Autumn.
*
- * Uses the last 90 days of daily usage plus `groupBy: "properties.apiKeyId"`
- * and rolls those daily totals into calendar-month buckets in API code.
+ * Covers the 90 days up to now, from the start of that UTC day, as daily
+ * usage grouped by `properties.apiKeyId`, and rolls those daily totals into
+ * calendar-month buckets in API code. The days come from 7-day slices (see
+ * `BY_API_KEY_SLICE_MS`): the slice holding today is always asked for live and
+ * first, so a team with no entity answers 404 there and gets an empty
+ * history; settled slices come from the cache when they can.
*/
export async function getTeamHistoricalUsageByApiKey(
teamId: string,
): Promise<HistoricalPeriodByApiKey[]> {
- if (!autumnClient) {
+ const client = autumnClient;
+ if (!client) {
throw new Error(
"Autumn client is not configured (AUTUMN_SECRET_KEY missing)",
);
@@ -429,18 +620,21 @@ export async function getTeamHistoricalUsageByApiKey(
const orgId = await lookupOrgId(teamId);
- let response: any;
+ const now = Date.now();
+ const windowStart =
+ Math.floor((now - HISTORICAL_WINDOW_MS) / DAY_MS) * DAY_MS;
+ const slices = byApiKeySlices(windowStart, now);
+ const currentSlice = slices[slices.length - 1];
+ const earlierSlices = slices.slice(0, -1);
+
+ let currentDays: ApiKeyUsageDay[];
try {
- response = await autumnClient.events.aggregate(
- {
- customerId: orgId,
- entityId: teamId,
- featureId: CREDITS_FEATURE_ID,
- range: HISTORICAL_RANGE,
- binSize: HISTORICAL_BIN_SIZE,
- groupBy: "properties.apiKeyId",
- },
- { timeoutMs: HISTORICAL_AGGREGATE_TIMEOUT_MS },
+ currentDays = await fetchApiKeyUsageSlice(
+ client,
+ orgId,
+ teamId,
+ currentSlice,
+ now,
);
} catch (err: any) {
const status = err?.statusCode ?? err?.status ?? err?.response?.status;
@@ -449,7 +643,32 @@ export async function getTeamHistoricalUsageByApiKey(
return [];
}
- return aggregateHistoricalPeriodsByApiKeyMonth(response.list ?? []);
+ const earlierDays = await mapWithConcurrency(
+ earlierSlices,
+ BY_API_KEY_SLICE_CONCURRENCY,
+ async slice => {
+ const settled = slice.end <= now - BY_API_KEY_SLICE_SETTLE_MS;
+ if (settled) {
+ const cached = await readCachedSlice(teamId, slice);
+ if (cached !== null) return cached;
+ }
+
+ const days = await fetchApiKeyUsageSlice(
+ client,
+ orgId,
+ teamId,
+ slice,
+ now,
+ );
+ if (settled) await writeCachedSlice(teamId, slice, days);
+ return days;
+ },
+ );
+
+ const days = [...earlierDays.flat(), ...currentDays].filter(
+ day => day.period >= windowStart,
+ );
+ return aggregateHistoricalPeriodsByApiKeyMonth(days);
}
/**