Timers

List all currently running or paused timers
Get a project’s timer
Edit a project’s timer
Start a project’s timer
Pause a project’s timer
Log the time in a project’s timer
Discard a project’s timer

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": "john.test@test.com",
      "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": "john.test@test.com",
    "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:

pending (no time has elapsed)
running
paused
stopped

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": "john.test@test.com",
    "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": "john.test@test.com",
    "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

When a timer is started, the currently running timer (if any) is paused.
Once a timer has been started, its entry date cannot be changed with the start action, even if it is paused or stopped. However, you can change the entry date for the timer when the timer is logged.

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": "john.test@test.com",
    "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

cannot_create_tags: The authenticated user is unable to create new tags

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

Topics

Resources

Account Management

Timers

List all currently running or paused timers

Parameters

Response

Get a project’s timer

Notes

Edit a project’s timer

Input

Start a project’s timer

Input

Notes

Pause a project’s timer

Notes

Log the time in a project’s timer

Input

Notes

Custom Error Codes

Discard a project’s timer

Response

About Freckle

Us & our company

Docs

You & your account