RescueTime Analytic Data API

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.

Work/Productivity Equivalents

The following table shows the productivity level equivalents referenced in the documentation below for various types of activities.

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. 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.

API Key Access

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.

OAuth2 Connection Access

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.

OAuth2 Access Scopes

When users connect their accounts to your application via OAuth2, you can specify access scopes to let the user know exactly how you will be using their RescueTime data. Scopes will be requested during the initial authorization request.

The following scopes are currently supported:

• time_data - Access activity history and summary time data or post offline time for the authorized user
• category_data - Access how much time the authorizing user spent in specific categories
• productivity_data - Access how much time the authorizing user spent in different productivity levels
• alert_data - Access the authorizing user's alert history
• highlight_data - Read from and post to the authorizing user's daily highlights list
• focustime_data - Access the authorizing user's Focus Session history and session starting and stopping

API Endpoints

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

Analytic Data API Documentation

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.

The Analytic 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.

Required Parameters

• key - Your API key OR access_token - The access token from the OAuth2 Connection
• format - Output format: csv or 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.

Output Formats

The Analytic Data API supports CSV and JSON output.

• csv - Layout provides rows of comma separated data with a header for column names at top
• json - Returns a JavaScript ready object with 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
  3. rows = Array of Arrays, data rows where each row is itself an array described by the row_headers

Example Queries

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

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

Daily Summary Feed API Documentation

The Daily Summary Feed API provides a high level rollup of 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).

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

• 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 be useful for deduplication of items in the feed
• date - Summary Date
• productivity_pulse - Overall productivity pulse. A scale between 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 Query

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

Alerts Feed API Documentation

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

Required Parameters

• key - Your API key OR access_token - The access token from the OAuth2 Connection
• op - Operation type: status or 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

• 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:

{
  "id": integer,           // Unique id of the user-defined alert
  "description": string,   // String representation of the alert definition
  "amount": float         // Number of hours 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:

{
  "id": integer,           // Unique id for the occurrence of the alert triggering
  "alert_id": integer,     // Unique id of the user-defined alert
  "description": string,   // Message generated by the triggered alert
  "created_at": datetime  // Time the alert was triggered (in user's time zone)
}

Example Queries

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

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

Daily Highlights Feed API Documentation

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

Required Parameters

• 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:

{
  "id": integer,           // Unique id, useful for polling for new items
  "description": string,   // Text of the highlight
  "date": date,           // Date the highlight was entered for (may differ from created_at)
  "created_at": datetime  // Timestamp when the highlight was entered
}

Example Query

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

Daily Highlights Post API Documentation

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

Required Parameters

• key - Your API key OR access_token - The access token from the OAuth2 Connection
• highlight_date - A string representing the date the highlight will be posted for. Format: 'YYYY-MM-DD' (unix timestamp also acceptable)
• description - A 255 character or shorter string containing the text that will be entered for the highlight. Should be representative of an action taken by the user

Optional Parameters

• 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. In the reporting UI, they will be collapsed under the expandable source label

Output Format

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

Example Request

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

Focus Session Trigger API Documentation

The Focus Session Trigger API makes it possible to start/end Focus Session on active devices as an alternative to starting/ending it manually from the desktop app. This is useful for automating Focus Session from 3rd party applications. An example would be starting/ending Focus Session at a certain time of day.

Service Access

The base URL to reach Focus Session Trigger API is:

For connections with an API key:

• https://www.rescuetime.com/anapi/start_focustime
• https://www.rescuetime.com/anapi/end_focustime

For OAuth2 connections:

• https://www.rescuetime.com/api/oauth/start_focustime
• https://www.rescuetime.com/api/oauth/end_focustime

Requires the focustime_data access scope to be granted by the user when the OAuth2 connection is initially set up.

Required Parameters

• key - Your API key OR access_token - The access token from the OAuth2 Connection
• duration - An integer representing the length of the Focus Session in minutes, and must be a multiple of 5 (5, 10, 15, 20...). A value of -1 can be passed to start Focus Session until the end of the day.

  Note: This parameter is not required for the end_focustime endpoint.

Output Format

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

Example Requests

POST: https://www.rescuetime.com/anapi/start_focustime?key=YOUR_API_KEY&duration=30

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

Focus Session Feed API Documentation

The Focus Session Feed API is a running log of recently triggered started/ended Focus Session sessions. This is useful for performing 3rd party app interactions whenever a new Focus Session has started/ended. Focus Session is 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 Focus Session Feed API is:

For connections with an API key:

• https://www.rescuetime.com/anapi/focustime_started_feed
• https://www.rescuetime.com/anapi/focustime_ended_feed

For OAuth2 connections:

• https://www.rescuetime.com/api/oauth/focustime_started_feed
• https://www.rescuetime.com/api/oauth/focustime_ended_feed

Requires the focustime_data access scope to be granted by the user when the OAuth2 connection is initially set up.

Required Parameters

• key - Your API key OR access_token - The access token from the OAuth2 Connection

Output Format

The Focus Session Feed API returns an array of JSON objects representing the Focus Session started/ended events in reverse chronological order:

{
  "id": float,             // UNIX timestamp that represents a unique id for the event
  "duration": integer,     // Initial length of time in minutes for the session (focustime_started_feed only)
  "created_at": datetime  // Time the session was started (in user's time zone)
}

Example Query

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

Offline Time POST API Documentation

The Offline Time Post API makes it possible to post offline time programmatically as an alternative to entering it manually on RescueTime.com. This is useful for capturing information from other systems. Examples include adding offline time after a meeting on a calendar app, or logging driving time based on location data.

Service Access

The base URL to reach Offline Time POST API is:

• For connections with an API key: https://www.rescuetime.com/anapi/offline_time_post
• For OAuth2 connections: https://www.rescuetime.com/api/oauth/offline_time_post - Requires the time_data access scope

Required Query Parameters

• key - Your API key OR access_token - The access token from the OAuth2 Connection

Required JSON Keys/Values

• start_time - A string representing the date/time for the start of the offline time block. Format: 'YYYY-MM-DD HH:MM:SS' (unix timestamp also acceptable)
• end_time/duration - Either a string representing the date/time for the end of the offline time block, OR an integer representing the duration of the offline time block in minutes
• activity_name - A 255 character or shorter string containing the text that will be entered as the name of the activity (e.g. "Meeting", "Driving", "Sleeping", etc)

Optional JSON Keys/Values

• activity_details - A 255 character or shorter string containing the text that will be entered as the details of the named activity

Output Format

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

Example Request

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

{
  "start_time": "2020-01-01 09:00:00",
  "duration": 60,
  "activity_name": "Meeting",
  "activity_details": "Daily Planning"
}

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.