Timers

List all currently running or paused timers

Get all the currently running or paused timers. The running timer will be shown first, then the paused timers. Only timers for the current user are returned.

GET /v2/timers

# cURL
$ curl -H "X-FreckleToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.letsfreckle.com/v2/timers

Parameters

Each parameter passed will filter the results, and parameters are chained (meaning that if you search by description and projects, it will only return the timers with that description text for those projects).

description
Optional string
Only timers containing this text in their description are returned.
Example: description=meeting
projects
Optional string
A comma-separated list of project IDs to filter by.
Example: projects=4,5,6
billable
Optional boolean
true: only show timers for billable projects
false: only show timers for unbillable projects

Response

Status: 200 OK
Link: <https://api.letsfreckle.com/v2/timers?page=2>; rel="next",
 <https://api.letsfreckle.com/v2/timers?page=5>; rel="last"
[
  {
    "id": 123456,
    "state": "running",
    "seconds": 180,
    "formatted_time": "00:03:00",
    "date": "2013-07-09",
    "description": "freckle work",
    "user": {
      "id": 5538,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.letsfreckle.com/v2/users/5538"
    },
    "project": {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.letsfreckle.com/v2/projects/37396"
    },
    "url": "https://api.letsfreckle.com/v2/projects/37396/timer",
    "start_url": "https://api.letsfreckle.com/v2/projects/37396/timer/start",
    "pause_url": "https://api.letsfreckle.com/v2/projects/37396/timer/pause",
    "log_url": "https://api.letsfreckle.com/v2/projects/37396/timer/log"
  }
]

Get a project’s timer

GET /v2/projects/:project_id/timer

# cURL
$ curl -H "X-FreckleToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.letsfreckle.com/v2/projects/:project_id/timer
Status: 200 OK
{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "freckle work",
  "user": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.letsfreckle.com/v2/projects/37396"
  },
  "url": "https://api.letsfreckle.com/v2/projects/37396/timer",
  "start_url": "https://api.letsfreckle.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.letsfreckle.com/v2/projects/37396/timer/pause",
  "log_url": "https://api.letsfreckle.com/v2/projects/37396/timer/log"
}

Notes

If a project does not have a currently running or paused timer, then the response will return a 404 status code.

Status: 404 Not Found

Timers can have the following state:

Edit a project’s timer

Updates the details for a project’s timer. If the timer does not exist, it will automatically be created.

PUT /v2/projects/:project_id/timer

# cURL
$ curl -X PUT -H "X-FreckleToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.letsfreckle.com/v2/projects/:project_id/timer
Status: 200 OK
{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "freckle work",
  "user": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.letsfreckle.com/v2/projects/37396"
  },
  "url": "https://api.letsfreckle.com/v2/projects/37396/timer",
  "start_url": "https://api.letsfreckle.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.letsfreckle.com/v2/projects/37396/timer/pause",
  "log_url": "https://api.letsfreckle.com/v2/projects/37396/timer/log"
}

Input

description
Optional string
The description that will be used when the timer is logged. Any tags or hashtags will be automatically parsed.

Start a project’s timer

PUT /v2/projects/:project_id/timer/start

# cURL
$ curl -X PUT -H "X-FreckleToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.letsfreckle.com/v2/projects/:project_id/timer/start
Status: 200 OK
Location: https://api.letsfreckle.com/v2/projects/1/timer
{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "freckle work",
  "user": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.letsfreckle.com/v2/projects/37396"
  },
  "url": "https://api.letsfreckle.com/v2/projects/37396/timer",
  "start_url": "https://api.letsfreckle.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.letsfreckle.com/v2/projects/37396/timer/pause",
  "log_url": "https://api.letsfreckle.com/v2/projects/37396/timer/log"
}

Input

entry_date
Optional string of a date in ISO 8061 format YYYY-MM-DD
If no value is provided, the current date will be used.
description
Optional string
The description that will be used when the timer is logged. Any tags or hashtags will be automatically parsed.

Notes

Pause a project’s timer

The response does not change if the timer has already been paused or does not exist

PUT /v2/projects/:project_id/timer/pause

# cURL
$ curl -X PUT -H "X-FreckleToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.letsfreckle.com/v2/projects/:project_id/timer/pause
Status: 200 OK
{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "freckle work",
  "user": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.letsfreckle.com/v2/projects/37396"
  },
  "url": "https://api.letsfreckle.com/v2/projects/37396/timer",
  "start_url": "https://api.letsfreckle.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.letsfreckle.com/v2/projects/37396/timer/pause",
  "log_url": "https://api.letsfreckle.com/v2/projects/37396/timer/log"
}

Notes

If a project does not have a currently running or paused timer, then the response will return a 404 status code.

Status: 404 Not Found

Log the time in a project’s timer

When a timer is logged, a new entry is created for the user with the description provided.

PUT /v2/projects/:project_id/timer/log

# cURL
$ curl -X PUT -H "X-FreckleToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.letsfreckle.com/v2/projects/:project_id/timer/log
Status: 204 No Content

Input

entry_date
Optional string of a date in ISO 8061 format YYYY-MM-DD
The date that will be used when creating an entry based on this timer. If no value is provided, then the entry_date provided when the timer was started will be used.
minutes
Optional integer
The number of minutes logged in the time entry. This number will automatically be rounded up based on the project’s “billing_increment” settings. If no value is provided, then the timer’s elapsed minutes will be used.
description.
Optional string
The description that will be used when the timer is logged. Any tags or hashtags will be automatically parsed.

Notes

If a project does not have a currently running or paused timer, then the response will return a 404 status code.

Status: 404 Not Found

Custom Error Codes

Discard a project’s timer

When a project’s timer is discarded, the timer is deleted and no time entry is recorded.

DELETE /v2/projects/:project_id/timer

# cURL
$ curl -X DELETE -H "X-FreckleToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.letsfreckle.com/v2/projects/:project_id/timer

Response

Status: 204 No Content