Intervals API Resource:

timer

The base URL for this resource is located at
https://api.myintervals.com/timer/

Timers are tricky business, complicated not just by the fact that there are two types of them (task timers and general timers). Executive users don't have access to them, and all time must be stored in UTC. For task timers, a user cannot have more than one timer for a particular task.

Timers rely on two fields: time (number of seconds) and starttime (timestamp). Whenever starttime is blank, it indicates that it's paused, and time contains amount of seconds recorded. If starttime is not blank, it indicates the timer is running.

To start a timer: set the starttime field to the current time in UTC.

To pause a timer: calculate the amount of time lapsed between the starttime and now, and sum that value with the value in the time field (i.e. time = time + (now - starttime)). Then nullify the starttime field.

To resume a timer: set the starttime field to the current time in UTC. Leave the existing value in the time field.

To apply a timer: A timer must be paused before it can be applied. Therefore, applying a timer to a time entry is as simple as reading the value of the time field.

Collection

Allowed HTTP Methods
Method	Group Access
GET	Administrator, Manager, Resource

Allowed Filters
Filter Name	Required?	Expects	Default	Description
generaltimers	no	boolean		Ordinarily, the list returns a list of active task timers. Appending this to your request returns the list of General Timers. Setting this to true returns the list of General Timers.
gettimerinfo	no	boolean		Setting this to true combines the list to return both general timers AND task timers in one request, and returns extra task information for task timers.
taskid	no	integer
personid	no	integer
projectid	no	integer
clientid	no	integer
sortfield	no	string		Sort the list by any of the following fields: lastupdate
sortdir	no	string		Sets the sort direction of the returned list. Must be either "ASC" or "DESC".
offset	no	integer		Return timers starting from the nth timer.
limit	no	integer	10	Sets a limit to the amount of timers returned in the response.

¹ Indicates that multiple values are allowed, in CSV format (e.g. "3,5,11,19").
² This field accepts HTML, but certain HTML elements may be stripped out.

Examples

To retrieve the entire list of this resource:

GET /timer/

To filter the list based on certain parameters:

GET /timer/?projectid={value}

Note: You can string together multiple filters.

Member

Allowed HTTP Methods
Method	Group Access
GET	Administrator, Manager, Resource
DELETE	Administrator, Manager, Resource
POST	Administrator, Manager, Resource
PUT	Administrator, Manager, Resource

Settable Fields for PUT and POST Requests
Field Name	Required?	Expects	Default	Description
taskid	no	integer		The ID of the task this timer is associated with. If left blank, this timer will be a General Timer
projectid	no	integer		The ID of the project this timer is associated with. Used for general timers when taskid is left blank.
personid	yes	integer		The ID of the person this timer is associated with.
starttime	no	datetime		REQUIRED IF time field is blank. Setting this field indicates that a timer is running. If missing, server time will be used when creating a new timer.
time	no	double		REQUIRED IF starttime field is blank.
timelapsed	no	double		Time elapsed since timer was started. This field is ready only.
name	no	string (255)		A description you want to apply to the timer.
lastupdate	no	datetime		The date on which the timer was last started or stopped

string (xxx) indicates a string with a maximum length of xxx characters.

Response Fields

The fields below are returned in GET responses. Boolean values are "t" / "f" strings. Numeric IDs and floats are returned as strings. Nullable fields may be JSON null.

Response Fields
Field Name	Nullable	Description
id	no	Unique identifier for the timer
taskid	yes	ID of the associated task (empty for a general timer)
personid	no	ID of the person this timer belongs to
starttime	yes	When the timer was started (empty when paused or not running)
time	yes	Accumulated time logged before the current running interval (decimal hours) (May be empty; often a string in JSON.)
name	yes	Timer label or description
lastupdate	no	When the timer was last started, stopped, or updated (UTC, YYYY-MM-DD HH:MM:SS)
notified	no	Whether a notification was sent for this timer ("t"/"f")
tasklocalid	yes	Local ID of the linked task (empty for general timers)
task	yes	Title of the linked task (empty for general timers)
timelapsed	yes	Elapsed time on the current run in decimal hours (read-only) (May be a string in JSON.)
isrunning	no	Whether the timer is currently running ("t"/"f")
totaltime	yes	Total elapsed decimal hours for this timer (read-only) (May be a string in JSON.)
key	no	Client correlation key (often matches `id`)
personlocalid	no	Local ID of the person in the Person app
person	no	Full name of the person
profile_image	yes	Profile image token or blob reference (empty when none)
datedue	yes	Due date of the linked task (empty when not applicable)
project	yes	Name of the linked project (empty when not applicable)
task_status	yes	Status label of the linked task (empty when not applicable)
projectid	yes	ID of the linked project (empty when not applicable)
projectactive	yes	Whether the linked project is active ("t"/"f") (Empty when there is no linked project.)
client	yes	Name of the linked client (empty when not applicable)
clientid	yes	ID of the linked client (empty when not applicable)
clientactive	yes	Whether the linked client is active ("t"/"f") (Empty when there is no linked client.)

Sample response object. Non-null values are strings in JSON (including IDs, numeric fields, and booleans as "t" / "f"). Nullable fields may be JSON null when absent.

{
    "id": "25524253",
    "taskid": null,
    "personid": "424758",
    "starttime": "2026-05-08 19:22:55",
    "time": "",
    "name": "Example Name",
    "lastupdate": "2026-05-08 19:22:55",
    "notified": "f",
    "tasklocalid": null,
    "task": null,
    "timelapsed": "14749.393385",
    "isrunning": "t",
    "totaltime": "14749.393385",
    "key": "25524253",
    "personlocalid": "3",
    "person": "John Reeve",
    "profile_image": "687e750306aef_blob",
    "datedue": null,
    "project": "Project Name",
    "task_status": "string value",
    "projectid": null,
    "projectactive": "t",
    "client": null,
    "clientid": null,
    "clientactive": "t"
}

When retrieving a collection (GET /timer/), the response envelope includes: personid (authenticated user's ID), status ("OK"), code (200), listcount (total matching records before limit/offset), and timer (array of result objects). Defaults, no cap on limit, and how to paginate using listcount are described in the API Introduction (Pagination).

Examples

To retrieve one member resource:

GET /timer/{id}/

Assuming no errors, the server will respond with 200 OK and the object requested.

To delete a particular member resource:

DELETE /timer/{id}/

Assuming no errors, the server will respond with 200 OK.

To create a new member resource:

POST /timer/

{
    "personid": value
}

Assuming no errors, the server will respond with 201 Created and the newly-created element. This will allow you to get the id of the item you just created and verify the field values. Note: Only required fields were listed here. The entire list of possible fields is above.

To update a member resource:

PUT /timer/{id}/

{
    "starttime": value,
    "time": value
}

Assuming no errors, the server will respond with 202 Accepted and the entire element. This will allow you to verify the field values.

Documentation

Resources

API Support

Looking for help?
Contact our support team.

OpenAPI

OpenAPI JSON spec (public)

Swagger UI on SwaggerHub

Start tracking time today

Join 5,000+ companies spending their time wisely with Intervals.

Try Intervals free