---
title: "Start a timer"
method: POST
path: "/api/v1/timer/start"
---

# Start a timer

`POST /api/v1/timer/start`

## Request

- Base URL: `https://tallymeter.com`
- URL: `https://tallymeter.com/api/v1/timer/start`
- Auth: HTTP bearer

Starts a new timer. Any currently running timer is stopped first (only one timer runs at a time). Requires the `timer` scope.

## Request body

- object
  - `description` string, nullable: What is being worked on, e.g. a ticket key plus summary.
  - `project_id` integer, nullable: One of your project ids from GET /api/v1/projects.

## Response `201`

Timer started

- object
  - `running` true, required
  - `entry` TimeEntry, required
    - `id` integer, required
    - `description` string, nullable, required
    - `project_id` integer, nullable, required
    - `project_name` string, nullable, required
    - `started_at` string, date-time, required: ISO-8601 UTC
    - `ended_at` string, date-time, nullable, required: ISO-8601 UTC; null while running
    - `duration_seconds` integer, required
    - `is_running` boolean, required
    - `source` 'web' | 'api' | 'mcp', required: Surface that created the entry
    - `agent` string, nullable, required: Name of the API token (= agent) that created the entry; null for web-created entries

## 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)