---
id: w8/m6/t002
title: GraphQL usage query accepts a period argument
worker: worker8
status: todo
estimate: 30m
depends_on: [w8/m6/t001]
---

## Objective

Add a `period` argument to the GraphQL `usage` query, matching REST's `?period=YYYY-MM` and MCP's `period` tool argument, so all three surfaces are capability-symmetric.

## Context

- `lego/backend/internal/usage/graphql.go` currently has no `period` argument; the resolver always calls the core `Usage` verb for the current month.
- `lego/backend/internal/usage/rest.go` already parses and validates `period` — reuse that validation logic rather than re-implementing it.

## Steps

1. Add an optional `period: String` argument to the `usage` GraphQL query.
2. Parse/validate it the same way REST does; default to the current month when omitted.
3. Pass it through to the core `Usage` verb.

## Files

- `lego/backend/internal/usage/graphql.go`

## Acceptance criteria

- [ ] `{ usage(period: "2026-06") { ... } }` returns June 2026's totals, matching `GET /v1/usage?period=2026-06`.
- [ ] Omitting `period` still defaults to the current month (no regression).

## Out of scope

- Dashboard wiring (t003).
