Time Doctor MCP: Data & Limitations

Note: This feature is currently available to beta customers only. Once generally available, the Time Doctor MCP feature will be available on all Time Doctor subscription plans and can be accessed by Owners, Admins, and Managers.

TL;DR:

Activity data is queryable through the Time Doctor MCP feature for a rolling two-year window (730 days).
Five per-request limits apply at once: date range (approximately 366 days), data age (730 days), team or group size (200 users), rows returned (500), and request time (approximately eight seconds).
Group selections expand to a maximum of 200 members; larger teams must be queried in batches.
Scope large or long-range queries by splitting date ranges, requesting summaries instead of raw events, and limiting selections to 200 users or fewer.

This section explains the data available when querying Time Doctor through the MCP feature, and the limits that apply to a single request. Understanding these limits helps scope queries so results return complete rather than partial.

Data Availability and Retention

Activity data is queryable for a rolling two-year window (730 days), matching Time Doctor's data retention policy. Request any date range that falls inside this window. The earliest queryable date moves forward each day as the window rolls. Dates older than the retention window are not available through this interface.

Per-Request Limits

Each query runs against a set of limits. These limits are independent of one another, and a request must satisfy all of them at once.

Limit	Current Value	What It Means
Date range per call	~366 days	The span between the start and end date of a single request. A range wider than this must be split across multiple requests.
Data age	730 days	How far back the start date may go (the retention window described above).
Team or group size per selection	200 users	When a group is selected, it expands to at most 200 of its members. See "Selecting Who to Query" below.
Rows per call	500	The maximum number of rows one request returns. Larger result sets are paged.
Request time	~8 seconds	Each request is capped at this duration. Very heavy queries, such as large teams over long ranges or raw event data, can hit this cap.

What "rows" means:

- A row is one line item in a result, regardless of the grouping used.
- A per-user summary of a 54-person department returns 54 rows—one per member.
- A raw worklog for that same team over a single week returns one row per tracked interval, easily several thousand.
- The 500-row cap is reached only by large, fine-grained result sets such as raw worklogs.

Nothing is lost when the cap is reached; the remaining rows appear on a further page.

What "request time" means:

- Each query must finish within approximately eight seconds or it is aborted; re-run it with a narrower scope.
- This limit is based on how difficult the query is to compute, not on how much data it returns.
- Queries are more likely to reach the time limit when they involve:
  - Large teams over long date ranges
  - Fine-grained grouping
  - Raw event data
  - The widest-scope queries are therefore the most likely to time out.

Selecting Who to Query (the 200-User Limit)

Keep any single query to 200 users or fewer, whether selecting a group or a list of individual users.

When querying by group, the group expands into its individual members and is capped at 200. If the group is larger, the result covers only the first 200 members, making a team total partial rather than complete.

When selecting users directly, the selection is not expanded the same way, but larger selections run into the other per-request limits instead, namely row count and request time. Either way, 200 remains the practical ceiling for a single selection.

To cover more than 200 people, split the group into batches of 200 or fewer, by sub-team or in chunks of users, and combine the results.

Best Practices for Large or Long-Range Queries

For queries that span long periods or large teams, scope each request to stay within the limits above:

Split long date ranges into windows.
Because a single request covers at most approximately 366 days, a two-year query must be broken into at least two windows — for example, two 12-month pulls — and combined. In practice, smaller windows, such as monthly or quarterly, are more reliable, because they return faster and stay well under the time cap.
Request summaries, not raw events.
Aggregated views, such as per-user totals or per-month trends, return a small, fixed number of rows no matter how long the range. Pulling raw, event-level data, such as individual worklog entries or screenshots, over a long range grows very quickly and is what typically hits row limits, paging, and timeouts.
Keep each user selection at or under 200 users.
For larger populations, query in batches and combine the results.
Request only the necessary fields.
Narrowing a query to specific metrics keeps responses small and avoids the response-size limit.

Should there be any inconsistencies or concerns regarding the article, contact support@timedoctor.com for prompt assistance.