RescueTime API Documentation

This page gives an overview of the RescueTime Developer APIs, details on how to access them, and the types of data that can be retrieved.

Connecting to the RescueTime API

There are two ways to connect to a user’s data in RescueTime, via API Keys or via an Oauth2 Connection. The API keys are ideal for personal use, while web services wishing to offer a way for their users to use their RescueTime data should use an Oauth2 connection.

Setting up an API key:

Users can set up an API key by going to their key management page and creating a new key. That key must be included with each API request. The user can revoke keys at any time.

Setting up an Oauth2 connection:

Please contact us and we’ll work with you to set up an Oauth2 application. After the user connects their account via Oauth2, an access token will be created. That access token must be included in each API request. The user can revoke access to a service at any time.

API Endpoints:

There are several API endpoints that can be used to access different types of data within RescueTime.

Analytic Data API

The Analytic Data API is targeted at bringing developers the prepared and pre-organized data structures already familiar through the reporting views of www.rescuetime.com.

Detailed documentation for the Analytic Data API

Daily Summary Feed API

The Daily Summary Feed API provides a structured rollup of daily data about the time logged by a user. This data includes: total time logged, time logged at each productivity level, average productivity pulse, and the time spent in each major category.

Detailed documentation for the Daily Summary Feed API

Alerts Feed API

The Alerts Feed API provides a feed of recent occurrences of user-defined alerts. It is a good way to let users define aspects of their data that they care about (“I want to spend more than 5 hours per day on All Productive Time”, for example) and then use that data in an external service.

Note: Alerts are a feature of RescueTime premium. This API will return empty results for non-premium users.

Detailed documentation for the Alerts Feed API

Highlights Feed API

The Highlights Feed API provides a feed of recently entered daily highlights.

Note: Highlights are a feature of RescueTime premium. This API will return empty results for non-premium users.

Detailed documentation for the Highlights Feed API

Highlights POST API

The Highlights POST API allows users to post a daily highlight entry programatically. An example use case is posting a new highlight whenever a software developer makes a new check-in to their GIT repository.

Note: Highlights are a feature of RescueTime premium. This API will return a 400 response for non-premium users.

Detailed documentation for the Highlights Post API

Documentation for the Analtyic Data API

RescueTime data is detailed and complicated. The Analytic Data API is targeted at bringing developers the prepared and pre-organized data structures already familiar through the reporting views of www.rescuetime.com. The data is read-only through the webservice, but you can perform any manipulations on the consumer side you want. Keep in mind this is a draft interface, and may change in the future. We do intend to version the interfaces though, so it is likely forward compatible.

The Analtyic Data API allows for parameterized access, which means you can change the subject and scope of data, and is especially targeted for developer use. The data can be accessed via the HTTP Query interface in several formats.

The Analytic Data API is presented as a read-only resource accessed by simple GET HTTP queries. This provides maximum flexibility with minimal complexity; you can use the provided API tools, or just research the documented parameters and construct your own queries.

Service Access

The base URL to reach this HTTP query API is:

  • For connections with an API key: https://www.rescuetime.com/anapi/data
  • For Oauth2 connections:
    • https://www.rescuetime.com/api/oauth/data - This is the least restritive url and requires the time_data access scope to be granted by the user when the Oauth2 connection is initially set up.
    • Restricted Report: https://www.rescuetime.com/api/oauth/overview_data - This url will restricts the output to top level category data only and requires the category_data access scope to be granted by the user when the Oauth2 connection is initially set up.
    • Restricted Report: https://www.rescuetime.com/api/oauth/category_data - This url will restricts the output to sub-category data only and requires the category_data access scope to be granted by the user when the Oauth2 connection is initially set up.
    • Restricted Report: https://www.rescuetime.com/api/oauth/productivity_data - This url will restricts the output to productivity data only and requires the productivity_data access scope to be granted by the user when the Oauth2 connection is initially set up.

About restricted reports: Restricted reports may be useful if your application requires a less-granular rollup of the data, such as the category view, but NOT the actual activities themselves. These restricted reports help ensure the user’s privacy, and may be a preferable option when asking them to link their accounts.

Required parameters

  1. key - [ Your API key ] OR access_token - [ the access token from the Oauth2 Connection ]
  2. format - [ csv | json ]

Query Parameters

Primary names are chosen for human reading. The short names are for when GET query length is at a premium. The alias is for understanding roughly how it maps into the language used in reporting views, and our own internal nicknames.

Principle name Short Alias Short Values Description
operationop "select" Currently, only one operation is supported, "select", and it is enforced on the server, and does not need to be sent from client.
versionvn "0" Only one version is live right now, and therefore doesn't need to be passed. It will be a serial number.
perspectivepvbyby 1 of "rank", "interval", "member" Consider this the X - axis of the returned data. It is what determines how your data is crunched serverside for ordered return.
  1. rank: (default) Organized around a calculated value, usually a sum like time spent.
  2. interval: Organized around calendar time.
resolution_timersintervali 1 of "month", "week", "day", "hour", "minute" Default is "hour". In an interval report, the X axis unit. In other words, data is summarizd into chunks of this size. "minute" will return data grouped into five-minute buckets, which is the most granular view available.
restrict_grouprggroupg 1 group name Provide the name of the group. Service will match that with your account to find group. Avoid re-using the same name for multiple groups when creating them. Currently we do not prevent this. First match will be returned.
restrict_beginrb date time Sets the start day for data batch, inclusive (always at time 00:00, start hour/minute not supported)
Format ISO 8601 "YYYY-MM-DD"
restrict_endre date time Sets the end day for data batch, inclusive (always at time 00:00, end hour/minute not supported)
Format ISO 8601 "YYYY-MM-DD"
restrict_kindrktaxonomyty 1 of "category", "activity", or "productivity" - "efficiency" is option when perspective is "interval"

Allows you to preprocess data through different statistical engines. The perspective dictates the main grouping of the data, this provides different aspects of that main grouping.

  1. overview: sums statistics for all activities into their top level category
  2. category: sums statistics for all activities into their sub category
  3. activity: sums statistics for individual applications / web sites / activities
  4. productivity: productivity calculation
  5. efficiency: efficiency calculation (not applicable in "rank" perspective)

restrict_thingrttaxontx name (of category, activity, or overview)

The name of a specific overview, category, application or website. For websites, use the domain component only if it starts with "www", eg. "www.nytimes.com" would be "nytimes.com". The easiest way to see what name you should be using is to retrieve a list that contains the name you want, and inspect it for the exact names.

restrict_thingyrysub_taxontn name

Refers to the specific "document" or "activity" we record for the currently active application, if supported. For example, the document name active when using Microsoft Word. Available for most major applications and web sites. Let us know if yours is not.

Output Formats

The Analytic Data API supports CSV and JSON output.

  1. CSV - layout provides rows of comma separated data with a header for column names at top.
  2. JSON - returns a JavaScript ready object. It has these properties:
    1. notes = String, a short explanation of the data envelope
    2. row_headers = Array, a label for the contents of each index in a row, in the order they appear in row
    3. rows = Array X Array, an array of data rows, where each row is itself an array described by the row_headers

Example Queries

To request information about the user's productivity levels, by hour, for the date of November 1, 2014:

https://www.rescuetime.com/anapi/data?key=YOUR_API_KEY&perspective=interval&restrict_kind=productivity&interval=hour&restrict_begin=2014-11-01&restrict_end=2014-11-01&format=json

To request a list of time spent in each top level category, ranked by duration for the date of November 1, 2014:

https://www.rescuetime.com/anapi/data?key=YOUR_API_KEY&perspective=rank&restrict_kind=overview&restrict_begin=2014-11-01&restrict_end=2014-11-01&format=csv

Questions?

If you have any questions about using the Analytic Data APIs, please open a support discussion.

Documentation for the Daily Summary Feed API

The Daily Summary Feed API provides a high level rollup of the the time a user has logged for a full 24 hour period (defined by the user’s selected time zone). This is useful for generating notifications that don’t need to be real-time and don’t require much granularity (for greater precision or more timely alerts, see the Alerts Feed API). This can be used to construct a customized daily progress report delivered via email. The summary can also be used to alert people to specific conditions. For example, if a user has more than 20% of their time labeled as ‘uncategorized’, that can be used to offer people a message to update their categorizations on the website.

Service Access

The base URL to reach this Daily Summary Feed API is:

  • For connections with an API key: https://www.rescuetime.com/anapi/daily_summary_feed
  • For Oauth2 connections: https://www.rescuetime.com/api/oauth/daily_summary_feed

Required parameters

  1. key - [ Your API key ] OR access_token - [ the access token from the Oauth2 Connection ]

Output Format

The Daily Summary Feed API returns an array of JSON objects representing rollup information for each day logged by the user in the previous two weeks. It does not include the current day, and new summaries for the previous day are available at 12:01 am in the user’s local time zone. The returned value for each daily summary includes the following information:

General information

  • id - Unix Timestamp representation of the date. Can use useful for deduplication of items in the feed.
  • date - Summary Date
  • productivity_pulse - Overall productivity pulse. A scale bewteen 0-100

Percentage representation of time spent in different categories (Float with one decimal place. Min: 0, Max: 100)

  • very_productive_percentage
  • productive_percentage
  • neutral_percentage
  • distracting_percentage
  • very_distracting_percentage
  • all_productive_percentage
  • all_distracting_percentage
  • uncategorized_percentage
  • business_percentage
  • communication_and_scheduling_percentage
  • social_networking_percentage
  • design_and_composition_percentage
  • entertainment_percentage
  • news_percentage
  • software_development_percentage
  • reference_and_learning_percentage
  • shopping_percentage
  • utilities_percentage

Numeric representation of HOURS spent in different categories (Float with two decimal places)

  • total_hours
  • very_productive_hours
  • productive_hours
  • neutral_hours
  • distracting_hours
  • very_distracting_hours
  • all_productive_hours
  • all_distracting_hours
  • uncategorized_hours
  • business_hours
  • communication_and_scheduling_hours
  • social_networking_hours
  • design_and_composition_hours
  • entertainment_hours
  • news_hours
  • software_development_hours
  • reference_and_learning_hours
  • shopping_hours
  • utilities_hours

String representations of time spent in different categories (format - Xh Ym Zs)

  • total_duration_formatted
  • very_productive_duration_formatted
  • productive_duration_formatted
  • neutral_duration_formatted
  • distracting_duration_formatted
  • very_distracting_duration_formatted
  • all_productive_duration_formatted
  • all_distracting_duration_formatted
  • uncategorized_duration_formatted
  • business_duration_formatted
  • communication_and_scheduling_duration_formatted
  • social_networking_duration_formatted
  • design_and_composition_duration_formatted
  • entertainment_duration_formatted
  • news_duration_formatted
  • software_development_duration_formatted
  • reference_and_learning_duration_formatted
  • shopping_duration_formatted
  • utilities_duration_formatted

Example Queries

To request a list of Daily Summaries for a user:

https://www.rescuetime.com/anapi/daily_summary_feed?key=YOUR_API_KEY

Questions?

If you have any questions about using the Daily Summary Feed API, please open a support discussion.

Documentation for the Alerts Feed API

The Alerts Feed API is a running log of recently triggered user defined alerts. This is a good event-based representation of data that the user cares about. Alerts are a premium feature and as such the API will always return zero results for users on the RescueTime Lite plan.

Service Access

The base URL to reach the Alerts Feed API is:

  • For connections with an API key: https://www.rescuetime.com/anapi/alerts_feed
  • For Oauth2 connections: https://www.rescuetime.com/api/oauth/alerts_feed - Requires the alert_data access scope to be granted by the user when the Oauth2 connection is initially set up.

Required parameters

  1. key - [ Your API key ] OR access_token - [ the access token from the Oauth2 Connection ]
  2. op - [ status | list ]

The op parameter determines what type of information about the alerts is returned. Passing op=list will return a definition list of all the alerts currently defined by the user. This is useful for presenting a list of the user's alerts to allow the user to select an alert_id value that will be used to filter subsequent queries.

Passing op a value of status is the default, and will return a list of recently triggered alerts in reverse-chronological order.

Optional parameters

  1. alert_id - [ Integer ID of an alert to filter on ]

Output Format

When passing op=list, The Alerts Feed API will return an array of JSON objects representing the currently active alerts that the user has defined. Each alert object has the following structure:

{
  :id => # The integer id of the user defined alert. Can be used for filtering the triggered alerts,
  :description => # The string representation of the alert definition. This is helpful if presenting a list to the user for selection,
  :amount => Float number representing the number of hours the user has defined for this alert’s threshold.
}
	

When passing op=status, the feed returns an array of JSON objects representing the actual triggering of alerts in reverse chronological order. Each object has the following structure:

{
  :id => # unique id for the occurence of the alert triggering
  :alert_id => # unique id for the user-defined alert, can be used to filter alerts
  :description => # The message generated by the triggered alert
  :created_at => # The time (in user’s selected time zone) that the alert was triggered
}
	

Example Queries

To request a list of for the user's active alerts:

https://www.rescuetime.com/anapi/alerts_feed?key=YOUR_API_KEY&op=list

To request a list of alert 12345 being triggered for the user:

https://www.rescuetime.com/anapi/alerts_feed?key=YOUR_API_KEY&op=status&alert_id=12345

Questions?

If you have any questions about using the Alerts Feed API, please open a support discussion.

Documentation for the Highlights Feed API

The Highlights Feed API is a list of recently entered Daily Highlight events. These are user-entered strings that are meant to provide qualitative context for the automatically logged time about the user’s activities. It is often used to keep a log of “what got done today”. Highlights are a premium feature and as such the API will always return zero results for users on the RescueTime Lite plan.

Service Access

The base URL to reach the Highlights Feed API is:

  • For connections with an API key: https://www.rescuetime.com/anapi/highlights_feed
  • For Oauth2 connections: https://www.rescuetime.com/api/oauth/highlights_feed - Requires the highlight_data access scope to be granted by the user when the Oauth2 connection is initially set up.

Required parameters

  1. key - [ Your API key ] OR access_token - [ the access token from the Oauth2 Connection ]

Output Format

The Highlights Feed API returns an array of JSON objects representing the highlights that have been entered by a user. The returned value for each highlight has the following structure:

{
  :id => # Unique Integer id to trigger off of. Useful for polling for new items
  :description => # String containing the text of the highlight,
  :date => # Date that the highlight was entered for (note: this may be different than created_at),
  :created_at => # Timestamp when the highlight was entered
}
	

Example Queries

To request a list of for the user's recently entered daily highlights:

https://www.rescuetime.com/anapi/highlights_feed?key=YOUR_API_KEY

Questions?

If you have any questions about using the Highlights Feed API, please open a support discussion.

Documentation for the Highlights POST API

The Highlights Post API makes it possible to post daily highlight events programmatically as an alternative to entering events manually on RescueTime.com. This is useful for capturing information from other systems and providing a view of the “output” that the user is creating (which is a counterpoint to the “input” attention data that RescueTime logs automatically). Examples include adding highlights whenever a code checkin is done, or marking an item in a to-do list application as complete.

Service Access

The base URL to reach Highlights POST API is:

  • For connections with an API key: https://www.rescuetime.com/anapi/highlights_post
  • For Oauth2 connections: https://www.rescuetime.com/api/oauth/highlights_post - Requires the highlight_data access scope to be granted by the user when the Oauth2 connection is initially set up.

Note: A POST request must be used for this API

Required parameters

  1. key - [ Your API key ] OR access_token - [ the access token from the Oauth2 Connection ]
  2. highlight_date - A string representing the date the highlight will be posted for. This should be in the format of ‘YYYY-MM-DD’, but a unix timestamp is also acceptable.
  3. description - A 255 character or shorter string containing the text that will be entered for the highlight. This should be representative of an action that was taken by the user.

Optional parameters

  1. source - A short string describing the ‘source’ of the action, or the label that should be applied to it. Think of this as a category that can group multiple highlights together in the UI. This is useful when many highlights will be entered. In the reporting UI, they will be collapsed under the expandable source label.

Output Format

A successful post will return at status code of 200. If there is an error, a status code of 400 will be returned.

Example Queries

To post a highlight about a code checkin the user has just made:

POST REQUEST:

https://www.rescuetime.com/anapi/highlights_post?key=YOUR_API_KEY&highlight_date=2014-11-01&description=CODE_CHECKIN_MESSAGE_HERE&source=check-in

Questions?

If you have any questions about using the Highlights Post API, please open a support discussion.

Security Considerations

When you enable access to your data, you generate a key that is saved in RescueTime's system. Essentially, this key provides an alternative read-only authentication to your data. You can keep this key private, in which case it's just as safe as your login and password, or publish it, without exposing your account to other access or risks beyond the scope of the data.

We assume data api access is being requested for use on the server side of things, presumably in some code of your own. In this case, you can protect the key as you would any other server side secret. It would never be seen in the browser, but used by your application to retrieve data from us then process and render yourself somehow. So in this case, the key provides read-only access to your data by arbitrary scope (within limits) through parameters.

As a user, you can revoke access to keys you have created by going to your Key Management Page. Any applications you have connected to via an Oauth2 connection, can be revoked by going to your connected applications page.