---
title: "Hours and earnings over a date range"
method: GET
path: "/api/v1/reports/time"
---

# Hours and earnings over a date range

`GET /api/v1/reports/time`

## Request

- Base URL: `https://tallymeter.com`
- URL: `https://tallymeter.com/api/v1/reports/time`
- Auth: HTTP bearer

Hours worked and money earned, billed and unbilled alike: the Reports page's numbers. Totals, one row per day/month/quarter/year, one per project, and the top tasks. Amounts are USD and priced from records: billed time is each entry's share of the invoice that billed it, time not invoiced yet is priced at its rate, time from before Tallymeter's own invoices (before `records_from`) at the rate it carried then. Finished entries only: a running timer counts once it stops. Requires the `reports:read` scope.

## Query parameters

- `from` string, date
- `to` string, date
- `bucket` 'day' | 'month' | 'quarter' | 'year'
- `tasks` integer

## Response `200`

Hours and money for the range

- object
  - `from` string, date, required
  - `to` string, date, required
  - `currency` 'USD', required
  - `records_from` string, date, nullable, required: first day Tallymeter's own invoices cover; null until the workspace has one
  - `totals` MoneyRow, required: Hours and USD for a set of finished entries. amount = billed_amount + rated_amount + unbilled_amount.
    - `seconds` integer
    - `hours` number
    - `amount` number: what the time earned: billed + rated + unbilled
    - `billed_amount` number: each entry's share of the invoice that billed it
    - `unpaid_amount` number: the part of billed_amount whose invoice is not paid yet
    - `rated_amount` number: time before records_from, at the rate it carried then
    - `never_paid_amount` number: billed and never paid; not in amount
    - `unbilled_amount` number: finished time not invoiced yet, at its rate
    - `billed_hours` number
    - `rated_hours` number
    - `never_paid_hours` number
    - `unbilled_hours` number
    - `unbillable_hours` number: time that was never billable; no amount
    - `unrecorded_hours` number: time before records_from with no rate on record; no amount
  - `bucket` 'day' | 'month' | 'quarter' | 'year', required
  - `periods` object[], required
    - `start` string, date
    - `seconds` integer
    - `hours` number
    - `amount` number: what the time earned: billed + rated + unbilled
    - `billed_amount` number: each entry's share of the invoice that billed it
    - `unpaid_amount` number: the part of billed_amount whose invoice is not paid yet
    - `rated_amount` number: time before records_from, at the rate it carried then
    - `never_paid_amount` number: billed and never paid; not in amount
    - `unbilled_amount` number: finished time not invoiced yet, at its rate
    - `billed_hours` number
    - `rated_hours` number
    - `never_paid_hours` number
    - `unbilled_hours` number
    - `unbillable_hours` number: time that was never billable; no amount
    - `unrecorded_hours` number: time before records_from with no rate on record; no amount
  - `by_project` object[], required
    - `project` string, nullable: null: entries with no project
    - `seconds` integer
    - `hours` number
    - `amount` number: what the time earned: billed + rated + unbilled
    - `billed_amount` number: each entry's share of the invoice that billed it
    - `unpaid_amount` number: the part of billed_amount whose invoice is not paid yet
    - `rated_amount` number: time before records_from, at the rate it carried then
    - `never_paid_amount` number: billed and never paid; not in amount
    - `unbilled_amount` number: finished time not invoiced yet, at its rate
    - `billed_hours` number
    - `rated_hours` number
    - `never_paid_hours` number
    - `unbilled_hours` number
    - `unbillable_hours` number: time that was never billable; no amount
    - `unrecorded_hours` number: time before records_from with no rate on record; no amount
  - `top_tasks` object[], required
    - `task` string
    - `project` string, nullable
    - `seconds` integer
    - `hours` number
    - `amount` number: what the time earned: billed + rated + unbilled
    - `billed_amount` number: each entry's share of the invoice that billed it
    - `unpaid_amount` number: the part of billed_amount whose invoice is not paid yet
    - `rated_amount` number: time before records_from, at the rate it carried then
    - `never_paid_amount` number: billed and never paid; not in amount
    - `unbilled_amount` number: finished time not invoiced yet, at its rate
    - `billed_hours` number
    - `rated_hours` number
    - `never_paid_hours` number
    - `unbilled_hours` number
    - `unbillable_hours` number: time that was never billable; no amount
    - `unrecorded_hours` number: time before records_from with no rate on record; no amount

## Other responses

- `401`: Missing or invalid token
- `403`: Token lacks the required scope, or the account has no active plan
- `422`: Validation failed

---

[API](https://skmtc.dev/tallymeter/apis/tallymeter-api.md) · [All operations](https://skmtc.dev/tallymeter/apis/tallymeter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tallymeter/apis/tallymeter-api/revisions/50044367b64e?raw)