Maple Harness home

Maple Harness 2.6.2 released! What's new in 2.6.2

Single userTeams & hubs

One person, one machine: the agent, the proxy and your own usage.

Several people, from one shared proxy up to a hub of hubs.

Query your usage #

On this page
  1. In plain words
  2. Before you start
  3. With usage query
    1. Spend by person this week
    2. Top models by cost
    3. Prompt-cache hit rate by tool
    4. Errors by provider in the last 24 hours
    5. Fallbacks, and why
    6. What auto chose
    7. A roll-up per hub
  4. With DuckDB
    1. The daily files
    2. The DuckDB file
    3. The lake
    4. PostgreSQL
  5. Into a spreadsheet
  6. Related

A cookbook of questions people ask of their usage, each with the command and what it printed. Every recipe here was run as shown; the output comes from a synthetic sample log (made-up people, models and traffic), so your figures will differ. Which store to query when is on Your data.

Figures are AI units as the providers reported them, or list-price estimates named _estimated. Neither is a bill, and the two are never added together.

In plain words #

  • What it is. Recipes: the questions people ask of their usage, each with the command and its output.
  • What to do. Copy a recipe and run it. maple-proxy usage query needs nothing else; the DuckDB recipes need the duckdb program. The setup page's Data & storage tab has the commands to start DuckDB on your own log.

Before you start #

  • maple-proxy usage query needs nothing else. It reads the daily files on this machine, and in central mode the shared PostgreSQL, so run it on a replica there. It works whether the proxy is running or not.
  • DuckDB recipes need DuckDB's command line (install it), plus INSTALL ducklake once for the lake and INSTALL postgres once for PostgreSQL.
  • -table in the commands below only makes DuckDB print plain-text tables; leave it out for its usual boxes.

With usage query #

The filters and --group-by keys are listed in Filter your data; --metrics picks the columns (maple-proxy usage query --help lists them all).

Spend by person this week #

On a team's proxy (here a replica in central mode, reading the shared PostgreSQL):

$ maple-proxy usage query --last 7d --group-by person,team --metrics requests,ai_units,cost_estimated
reading the shared usage log: 60794 line(s) over 25 day(s), every replica
Usage  (last=7d)
  PERSON        TEAM      REQUESTS  AI_UNITS  COST_ESTIMATED
  hana          data         1,958   449.116          37.589
  kai           platform     1,301   344.976           6.408
  dmitri        data         1,137   339.746          11.264
  jun           apps         1,113   267.600           3.086
  unattributed  no team      1,078   189.912          13.566
  gus           apps         1,078   312.081          21.720
  farah         apps         1,030   381.768          35.208
  carol         apps           998   465.080          41.425
  bob           platform       921   361.640          30.599
  lena          platform       918   447.030          47.751
  alice         apps           902   249.506          21.790
  ivan          data           894   278.534          20.519
  eve           data           790   321.529          22.234
  total                     14,118  4408.517         313.160

  Person: unattributed (- in JSON and CSV) is a request no person was recorded for: sent before people were set
  up, or with an access token tied to no person. local is a request from this machine without an access token, once
  people are set up.
  Team: no team (- in JSON and CSV) is a request whose person has no team, or that no person was recorded for.
  Figures named _estimated are the proxy's estimates, not measurements or bills.
maple-proxy usage query --last 7d --group-by team,person on a central-mode replica, reading the shared usage log of every replica: thirteen rows of team, person, requests, AI units and estimated cost, such as data hana 1,958 requests 449.116 AI units, platform kai 1,301 and 344.976, and an unattributed row; total 14,118 requests and 4408.517 AI units.maple-proxy usage query --last 7d --group-by team,person on a central-mode replica, reading the shared usage log of every replica: thirteen rows of team, person, requests, AI units and estimated cost, such as data hana 1,958 requests 449.116 AI units, platform kai 1,301 and 344.976, and an unattributed row; total 14,118 requests and 4408.517 AI units.
The same question by team, on a replica in central mode: every replica's usage, from PostgreSQL.

unattributed is requests no person was recorded for: sent before people were set up, or with an access token tied to no person. local (not in this example) is a request from the proxy's own machine without an access token, once people are set up. In --format json and --format csv the unattributed group is -, and --person unattributed and --person - both pick it. The same way, no team is requests whose person has no team, or that have no person; JSON and CSV show -, and --team - picks it. For week by week, group by day and add the days up in a spreadsheet, or use the DuckDB recipe over PostgreSQL.

Top models by cost #

$ maple-proxy usage query --last 30d --group-by model --metrics requests,ai_units,cost_estimated --limit 5
Usage  (last=30d)
  MODEL            REQUESTS  AI_UNITS  COST_ESTIMATED
  gpt-6-sol           6,725  2296.597               -
  claude-sonnet-5     2,730  1113.135               -
  qwen4-coder-32b     2,206     0.000               -
  claude-opus-5       2,161  2894.373         558.124
  gpt-6-mini          1,258   100.627          25.353
  total              16,397  6495.393         624.941

  Figures named _estimated are the proxy's estimates, not measurements or bills.

--limit keeps the biggest groups by request count. A local model reports no AI units (0.000), and a provider without list prices has no cost_estimated (-). list_cost_usd is the request priced at the provider's published list prices whether or not estimate_cost is on (the figure monthly dollar budgets count, estimated, through this proxy only); lines written before schema version 6 have none.

Prompt-cache hit rate by tool #

$ maple-proxy usage query --last 7d --group-by agent --metrics requests,hit_rate,cached_tokens,lost
Usage  (last=7d)
  AGENT          REQUESTS  HIT_RATE  CACHED_TOKENS  LOST
  maple-harness     1,167     62.7%          25.1M    53
  claude-code       1,112     63.5%          39.9M    67
  other               684     60.6%          16.6M    51
  opencode            183     60.0%           6.3M     8
  total             3,146     62.5%            88M   179

hit_rate is the share of input tokens read from the provider's prompt cache; lost counts requests whose cache was lost. Why a cache missed: Why the cache missed.

Errors by provider in the last 24 hours #

$ maple-proxy usage query --last 24h --outcome error --group-by provider,error_class --metrics requests
Usage  (last=24h0m0s&outcome=error)
  PROVIDER             ERROR_CLASS        REQUESTS
  github-copilot       quota exhausted           3
  github-copilot       request too large         3
  anthropic            unreachable               2
  github-copilot       server error              2
  anthropic            quota exhausted           1
  anthropic            rate limited              1
  apple                rate limited              1
  github-copilot       canceled                  1
  github-copilot       not authorised            1
  github-copilot       overloaded                1
  github-copilot       unreachable               1
  github-copilot-work  server error              1
  total                                         18

--last 24h is a rolling window; --last 1d would be today since midnight UTC. The Health tab and Provider health show the same over time.

Fallbacks, and why #

$ maple-proxy usage query --last 7d --outcome fallback --group-by route_reason --metrics requests,ai_units
Usage  (last=7d&outcome=fallback)
  ROUTE_REASON              REQUESTS  AI_UNITS
  fallback:overloaded             22    16.024
  fallback:rate limited           18    11.170
  fallback:quota exhausted        14     3.961
  total                           54    31.155

Each line is a request a fallback answered; route_reason names the class of error that sent it there. Add model to --group-by to see which model stepped in.

What auto chose #

$ maple-proxy usage query --last 7d --requested auto --group-by auto_weight,model --metrics requests,ai_units,error_rate
Usage  (last=7d&requested=auto)
  AUTO_WEIGHT  MODEL            REQUESTS  AI_UNITS  ERROR_RATE
  heavy        gpt-6-sol             182    61.953        4.4%
  light        gpt-6-sol             143    49.017        2.1%
  light        gpt-6-mini            139    13.099        3.6%
  medium       gpt-6-sol             138    49.203        2.9%
  medium       qwen4-coder-32b       118     0.000        3.4%
  heavy        qwen4-coder-32b        67     0.000        3.0%
  medium       claude-sonnet-5        60    20.833        8.3%
  heavy        claude-sonnet-5        55    37.844        3.6%
  light        claude-opus-5          52    52.643        0.0%
  heavy        gpt-6-mini             43     7.469        2.3%
  light        claude-sonnet-5        40    22.091        2.5%
  heavy        claude-haiku-5         19     3.188        0.0%
  heavy        claude-opus-5          17    10.123        5.9%
  total                            1,073   327.464        3.4%

maple-proxy usage auto-report and How auto did go further.

A roll-up per hub #

On a top hub with proxies below it, by the proxy each request started on:

$ maple-proxy usage query --group-by origin_proxy --metrics client_requests,requests,ai_units_spent
Usage  (all requests)
  ORIGIN_PROXY  CLIENT_REQUESTS  REQUESTS  AI_UNITS_SPENT
  alice-laptop               15        34           4.950
  platform-hub                8        16           2.640
  top-hub                     4         4           1.320
  total                      27        54           8.910

  Includes the usage children sent up. requests counts lines, one per proxy a request passed through; client_requests counts each request once, and ai_units_spent and cost_estimated_spent count spend once, where it was spent.

Use client_requests and ai_units_spent to count each request and its spend once; requests counts a line on every proxy a request passed through. Add person to --group-by for who asked.

With DuckDB #

The same records, in plain SQL. Each source below gives you a usage table or view and the named views (maple.requests, maple.daily_spend, maple.sessions, maple.people and the rest), so a query written for one works on the others.

The daily files #

maple-proxy usage schema --format sql --views > maple.sql
duckdb -cmd ".read maple.sql"

Spend by provider, week by week (saved as weekly-provider.sql):

SELECT date_trunc('week', day)::DATE AS week, provider,
       sum(requests) AS requests, round(sum(ai_units), 1) AS ai_units
FROM maple.daily_spend
WHERE day >= DATE '2026-09-21' AND day < DATE '2026-10-05'
GROUP BY ALL
ORDER BY week, ai_units DESC;
$ duckdb -table -cmd ".read maple.sql" -f weekly-provider.sql
+------------+---------------------+----------+----------+
|    week    |      provider       | requests | ai_units |
+------------+---------------------+----------+----------+
| 2026-09-21 | github-copilot      | 1764     | 653.2    |
| 2026-09-21 | anthropic           | 406      | 553.5    |
| 2026-09-21 | github-copilot-work | 385      | 121.0    |
| 2026-09-21 | openai              | 323      | 26.7     |
| 2026-09-21 | openrouter          | 62       | 2.2      |
| 2026-09-21 | apple               | 103      | 0.0      |
| 2026-09-21 | ollama              | 983      | 0.0      |
| 2026-09-28 | anthropic           | 811      | 732.5    |
| 2026-09-28 | github-copilot      | 1964     | 668.0    |
| 2026-09-28 | github-copilot-work | 273      | 99.3     |
| 2026-09-28 | openai              | 410      | 31.5     |
| 2026-09-28 | openrouter          | 65       | 4.6      |
| 2026-09-28 | ollama              | 342      | 0.0      |
| 2026-09-28 | apple               | 119      | 0.0      |
+------------+---------------------+----------+----------+

The cache hit rate by tool, counted in requests rather than tokens (saved as cache-by-tool.sql):

SELECT agent,
       count(*) FILTER (WHERE cache_class = 'hit') AS hits,
       count(*) FILTER (WHERE cache_class IN ('hit', 'partial', 'miss', 'lost')) AS classified,
       round(100.0 * hits / classified, 1) AS hit_pct
FROM maple.requests
WHERE day >= DATE '2026-10-02'
GROUP BY agent
ORDER BY classified DESC;
$ duckdb -table -cmd ".read maple.sql" -f cache-by-tool.sql
+---------------+------+------------+---------+
|     agent     | hits | classified | hit_pct |
+---------------+------+------------+---------+
| claude-code   | 635  | 1063       | 59.7    |
| maple-harness | 518  | 907        | 57.1    |
| other         | 392  | 698        | 56.2    |
| opencode      | 292  | 490        | 59.6    |
+---------------+------+------------+---------+

Over many months the daily files are many files; maple-proxy usage compact packs them into one Parquet file per month, and --source parquet-monthly makes the same views over those (Lots of history?).

The DuckDB file #

maple-proxy usage duckdb loads the daily files into one DuckDB file and, run again, adds only what they gained:

$ maple-proxy usage duckdb
/home/demo/.config/maple-harness/usage/analytics/maple_usage.duckdb: 68,469 request row(s), 0 event row(s); loaded 68,469 new line(s) from 120 daily file(s) in 636ms
query it: duckdb /home/demo/.config/maple-harness/usage/analytics/maple_usage.duckdb -c "SELECT * FROM maple.daily_spend ORDER BY day DESC LIMIT 20"

The two biggest models of each month (saved as monthly-model.sql):

SELECT date_trunc('month', day)::DATE AS month, model,
       sum(requests) AS requests, round(sum(ai_units), 1) AS ai_units
FROM maple.daily_spend
GROUP BY month, model
QUALIFY row_number() OVER (PARTITION BY month ORDER BY sum(ai_units) DESC) <= 2
ORDER BY month, ai_units DESC;
$ duckdb -table -readonly ~/.config/maple-harness/usage/analytics/maple_usage.duckdb -f monthly-model.sql
+------------+-----------------+----------+----------+
|   month    |      model      | requests | ai_units |
+------------+-----------------+----------+----------+
| 2026-07-01 | claude-opus-5   | 1077     | 1374.1   |
| 2026-07-01 | claude-sonnet-5 | 3310     | 1355.3   |
| 2026-08-01 | claude-opus-5   | 1825     | 2752.9   |
| 2026-08-01 | gpt-6-sol       | 6343     | 2150.7   |
| 2026-09-01 | claude-opus-5   | 2013     | 2660.0   |
| 2026-09-01 | gpt-6-sol       | 6813     | 2292.6   |
| 2026-10-01 | claude-opus-5   | 647      | 901.7    |
| 2026-10-01 | gpt-6-sol       | 1906     | 639.5    |
+------------+-----------------+----------+----------+

July starts part way through: the DuckDB file follows the daily files, and the 90-day cleanup had deleted the days before July 11. -readonly lets you query it while the proxy's daily refresh might write to it.

The lake #

Attach it read-only (how), and the same query reaches back past the cleanup:

$ duckdb -table -cmd ".read lake.sql" -f monthly-model.sql
+------------+-----------------+----------+----------+
|   month    |      model      | requests | ai_units |
+------------+-----------------+----------+----------+
| 2026-06-01 | claude-opus-5   | 1259     | 1724.4   |
| 2026-06-01 | gpt-6-sol       | 3982     | 1232.7   |
| 2026-07-01 | claude-opus-5   | 1731     | 2241.6   |
| 2026-07-01 | claude-sonnet-5 | 4781     | 2000.4   |
| 2026-08-01 | claude-opus-5   | 1825     | 2752.9   |
| 2026-08-01 | gpt-6-sol       | 6343     | 2150.7   |
| 2026-09-01 | claude-opus-5   | 2013     | 2660.0   |
| 2026-09-01 | gpt-6-sol       | 6813     | 2292.6   |
| 2026-10-01 | claude-opus-5   | 647      | 901.7    |
| 2026-10-01 | gpt-6-sol       | 1906     | 639.5    |
+------------+-----------------+----------+----------+
A DuckDB session attached to the lake read-only: the snapshots that inserted rows (2, 4 and 9), the lake at version 2 with 67,720 requests up to 2026-10-07 against 68,469 up to 2026-10-08 now, and requests and AI units per month from June to October.A DuckDB session attached to the lake read-only: the snapshots that inserted rows (2, 4 and 9), the lake at version 2 with 67,720 requests up to 2026-10-07 against 68,469 up to 2026-10-08 now, and requests and AI units per month from June to October.
The lake in DuckDB: its snapshots, the lake as it was at one of them, and history from before the 90-day cleanup.

Time travel: the same table as it was at an earlier snapshot (saved as then-and-now.sql; list the snapshots with FROM maple_lake.snapshots()):

SELECT 'version 2' AS lake, count(*) AS requests, max("at")::DATE AS newest_day FROM main.usage AT (VERSION => 2)
UNION ALL
SELECT 'now', count(*), max("at")::DATE FROM main.usage;
$ duckdb -table -cmd ".read lake.sql" -f then-and-now.sql
+-----------+----------+------------+
|   lake    | requests | newest_day |
+-----------+----------+------------+
| version 2 | 67720    | 2026-10-07 |
| now       | 68469    | 2026-10-08 |
+-----------+----------+------------+

More on snapshots: Time travel and snapshots.

PostgreSQL #

In central mode, two ways to read the shared PostgreSQL from DuckDB, both read-only. Use a role that can only read (the grants). In storage mode redis there is no PostgreSQL: usage schema --source postgres is refused and says so; usage query and usage export on a replica read every replica's usage.

The named views over PostgreSQL. The connection string stays in an environment variable and is read when you query; it is never written into the SQL:

export MAPLE_POSTGRES_DSN='postgres://analyst@db.example:5432/maple?sslmode=require'
export PGPASSWORD='...'      # kept out of the connection string
maple-proxy usage schema --source postgres --dsn-env MAPLE_POSTGRES_DSN --views > maple-pg.sql

Spend by person per week for one team (saved as weekly-person.sql):

SELECT date_trunc('week', day)::DATE AS week, person, team,
       sum(requests) AS requests, round(sum(ai_units), 1) AS ai_units
FROM maple.daily_spend
WHERE team = 'platform' AND day >= DATE '2026-09-21' AND day < DATE '2026-10-05'
GROUP BY ALL
ORDER BY week, ai_units DESC;
$ duckdb -table -cmd ".read maple-pg.sql" -f weekly-person.sql
+------------+--------+----------+----------+----------+
|    week    | person |   team   | requests | ai_units |
+------------+--------+----------+----------+----------+
| 2026-09-21 | bob    | platform | 1103     | 588.6    |
| 2026-09-21 | lena   | platform | 1408     | 529.8    |
| 2026-09-21 | kai    | platform | 1012     | 373.9    |
| 2026-09-28 | kai    | platform | 1338     | 648.8    |
| 2026-09-28 | lena   | platform | 1274     | 429.1    |
| 2026-09-28 | bob    | platform | 1355     | 298.4    |
+------------+--------+----------+----------+----------+

ATTACH, for your own SQL over the typed view maple_usage_rows (every usage column). The password comes from PGPASSWORD, so it is not in the file (saved as attach-pg.sql):

ATTACH 'host=127.0.0.1 port=25432 dbname=maple user=analyst' AS live (TYPE postgres, READ_ONLY);
SELECT provider, error_class, count(*) AS errors
FROM live.public.maple_usage_rows
WHERE error_class IS NOT NULL AND "at" >= TIMESTAMPTZ '2026-10-08 00:00:00+00'
GROUP BY ALL
ORDER BY errors DESC
LIMIT 5;
$ duckdb -table -f attach-pg.sql
+----------------+-----------------+--------+
|    provider    |   error_class   | errors |
+----------------+-----------------+--------+
| github-copilot | server error    | 14     |
| github-copilot | quota exhausted | 9      |
| github-copilot | overloaded      | 8      |
| github-copilot | unreachable     | 7      |
| github-copilot | canceled        | 6      |
+----------------+-----------------+--------+

PostgreSQL holds only storage.retention_days; for anything older, query the lake. Reading PostgreSQL through these views is slower than reading the lake, and every query is work for the live database: for long ranges and dashboards, prefer the lake.

Into a spreadsheet #

A summary as CSV. Any usage query prints CSV with --format csv; the notes go to the terminal, not the file:

$ maple-proxy usage query --since 2026-09-01 --until 2026-10-01 --group-by day,provider --metrics requests,ai_units,cost_estimated --format csv > september.csv
note: Figures named _estimated are the proxy's estimates, not measurements or bills.
$ head -4 september.csv
day,provider,requests,ai_units,cost_estimated
2026-09-01,github-copilot,447,189.95708199999996,
2026-09-01,anthropic,115,91.76395600000001,16.934755000000003
2026-09-01,ollama,27,0,

Every request as CSV (or Parquet), with every column of the usage record:

$ maple-proxy usage export --format csv --since 2026-09-01 --until 2026-10-01 --out usage-september.csv
wrote 17211 request(s) from 91 file(s) to usage-september.csv

An Excel file from DuckDB, from any source above. DuckDB's excel extension writes .xlsx (INSTALL excel once). From the lake, a daily summary over its whole history (saved as xlsx.sql):

LOAD excel;
COPY (
  SELECT day, provider, model, sum(requests) AS requests, round(sum(ai_units), 3) AS ai_units
  FROM maple.daily_spend
  GROUP BY ALL
  ORDER BY day, provider, model
) TO 'daily-spend.xlsx' WITH (FORMAT xlsx, HEADER true);
duckdb -cmd ".read lake.sql" -f xlsx.sql

Spreadsheets open the CSV and .xlsx files directly. The setup page's Usage data card also has an Export button for CSV or Parquet.

Made with ❤️ by Kinn Coelho Juliao in Ottawa, eh — fuelled by double-doubles, bud. 🍁