Timers

Start Timer

Changed on Sep 18, 2026

Start a timer for the authenticated user on a given task.

Only one timer can run per user at a time. If the user already has a timer running on another task, that timer is stopped automatically before the new one starts; the stopped run is committed to a time record on its own date (the date the timer was started, which may not be today for cross-midnight runs).

See Concepts for timer semantics.

post/timers

Request

Base URL
https://api.everhour.com
Auth
API key in header X-Api-Key
TypeScript
https://skmtc.dev/everhour/apis/everhour-api/docs/timers/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

taskstring

Task ID

userDatestring

commentstring

Example request

{
  "task": "ev:9876543210",
  "userDate": "2018-01-16",
  "comment": "some notes"
}

Response

Created

status'active' | 'stopped' required

durationnumber

Timer duration in seconds

todaynumber

Today time by user in the timer task

startedAtstring

userDatestring

commentstring

Example response

{
  "status": "active",
  "duration": 16,
  "today": 7200,
  "startedAt": "2018-01-16 12:42:59",
  "userDate": "2018-01-16",
  "task": {
    "id": "ev:9876543210",
    "name": "Task Name",
    "type": "task",
    "url": "https://github.com/acme/web/issues/8688",
    "number": "ED-774",
    "projects": [
      "ev:1234567890"
    ],
    "section": 1234,
    "labels": [
      "high",
      "bug"
    ],
    "position": 1,
    "dueAt": "2018-03-05 16:00:00",
    "dueOn": "2024-10-31",
    "status": "open",
    "completedAt": "2024-01-24 14:36:20",
    "createdAt": "2023-04-07 13:11:20",
    "createdBy": 1304,
    "assignees": [
      {
        "userId": 1304,
        "accountId": "gh:313991",
        "accountName": "jbender"
      }
    ],
    "iteration": "In Progress",
    "color": "#edacc7",
    "comments": 1,
    "time": {
      "total": 7200,
      "users": {
        "1304": 3600,
        "1543": 3600
      },
      "timerTime": 5400
    },
    "estimate": {
      "total": 7200,
      "type": "overall",
      "users": {
        "1304": 3600,
        "1543": 3600
      }
    },
    "attributes": {
      "Client": "Everhour",
      "Priority": "high"
    },
    "metrics": {
      "efforts": 42,
      "expenses": 199
    }
  },
  "user": {
    "id": 1304,
    "email": "john.bender@example.com",
    "name": "John Bender",
    "headline": "CEO",
    "phone": "+1 555 0100",
    "externalId": "M-3490",
    "avatarUrl": "https://d36887svjhykt4.cloudfront.net/users/1304-15ea197d07ca81.jpg",
    "avatarUrlLarge": "https://d36887svjhykt4.cloudfront.net/users/1304-15ea197d10830c.jpg",
    "role": "admin",
    "status": "active",
    "type": "employee",
    "createdAt": "2016-08-13 15:27:30",
    "isEmailVerified": true,
    "capacity": 144000,
    "cost": 2500,
    "groups": [
      {
        "id": 1,
        "name": "Admins"
      }
    ],
    "permissions": {
      "billingBudgets": "write",
      "userLimits": "write",
      "costs": "write",
      "invoices": "write",
      "expenses": "write"
    },
    "timeTrackingPolicy": {
      "allowTimeWithoutTask": true,
      "allowManualTimeInput": true,
      "allowCompletedTaskTime": true,
      "allowTimeWithoutEstimate": true,
      "allowManageEstimates": true,
      "lockTimeAfter": 2,
      "lockTimePeriod": "days"
    }
  },
  "currentTaskTime": {
    "id": 2660155,
    "time": 3600,
    "user": 1304,
    "date": "2018-01-20",
    "task": {
      "id": "ev:9876543210",
      "name": "Task Name",
      "type": "task",
      "url": "https://github.com/acme/web/issues/8688",
      "number": "ED-774",
      "projects": [
        "ev:1234567890"
      ],
      "section": 1234,
      "labels": [
        "high",
        "bug"
      ],
      "position": 1,
      "dueAt": "2018-03-05 16:00:00",
      "dueOn": "2024-10-31",
      "status": "open",
      "completedAt": "2024-01-24 14:36:20",
      "createdAt": "2023-04-07 13:11:20",
      "createdBy": 1304,
      "assignees": [
        {
          "userId": 1304,
          "accountId": "gh:313991",
          "accountName": "jbender"
        }
      ],
      "iteration": "In Progress",
      "color": "#edacc7",
      "comments": 1,
      "time": {
        "total": 7200,
        "users": {
          "1304": 3600,
          "1543": 3600
        },
        "timerTime": 5400
      },
      "estimate": {
        "total": 7200,
        "type": "overall",
        "users": {
          "1304": 3600,
          "1543": 3600
        }
      },
      "attributes": {
        "Client": "Everhour",
        "Priority": "high"
      },
      "metrics": {
        "efforts": 42,
        "expenses": 199
      }
    },
    "comment": "some notes"
  }
}

Changes

Sep 18, 202692850a5e60d1 Revision changes
- warning
  added the new completed enum value to the // response property for the response status
- warning
  added the new completed enum value to the / response property for the response status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status

Operation history