---
name: givegigs-time
description: Track billable and non-billable hours with live stopwatch timers, manual logs, project links, and unbilled reports.
---

# Time Tracking & Stopwatch Timer

Base URL: `https://givegigs.com`. Authenticate with `Authorization: Bearer givegigs-...` or `X-API-Key`. Private reads require `read` scope; mutations require `write` scope.

Web interface: `https://givegigs.com/timer`.

## Live Stopwatch Timer

Only one active timer can run at a time per user account.

### Check Current Running Timer
```http
GET /api/time/timer
Authorization: Bearer givegigs-...
```
Returns running timer object with `id`, `startTime`, `description`, `isBillable`, `project`, or `null` if no timer is running.

### Start a Timer
```http
POST /api/time/timer
Content-Type: application/json
Authorization: Bearer givegigs-...

{
  "projectId": "proj_123",
  "taskId": "task_456",
  "description": "Auditing liquidator manifest and condition evidence",
  "isBillable": true,
  "tags": ["flipping", "manifest-audit"]
}
```
*Returns 400 if another timer is already running. Stop the current timer before starting a new one. Omitted `projectId` attaches the account's default project.*

### Stop and Save Running Timer
```http
PUT /api/time/timer
Content-Type: application/json
Authorization: Bearer givegigs-...

{
  "description": "Finished auditing 45 manifest line items",
  "isBillable": true
}
```
Calculates exact elapsed duration in seconds and persists the completed time entry.

### Discard Running Timer
```http
DELETE /api/time/timer
Authorization: Bearer givegigs-...
```
Aborts and deletes the active timer without saving a billable entry.

## Time Entries & Reporting

- `GET /api/time?startDate=2026-10-01&endDate=2026-10-31` - List historical time entries.
- `POST /api/time` - Manually log past work: `{ "startTime": ISOString, "endTime": ISOString, "duration": 3600, "description": "Offline photo editing", "isBillable": true, "projectId": "proj_123" }`.
- `GET /api/time/:id` / `PUT /api/time/:id` / `DELETE /api/time/:id` - Manage a specific entry.
- `GET /api/time/reports` - Aggregated hours, billable amounts, and group totals by project or date range.
- `GET /api/time/unbilled?clientId=:clientId` - Retrieve unbilled entries ready to import into invoices (`/api/invoice`).

[Light Skill](https://givegigs.com/skill.md) · [Complete Reference](https://givegigs.com/skill-heavy.md)