If you’re new to Hubstaff’s API, we recommend reviewing the most commonly asked questions below:

Why am I receiving an invalid token error?

The token generated from the Personal Access Tokens page is a refresh token, not an access token. Before making an API request, exchange it for an access token using the process described in the personal access token documentation.

Access tokens are valid for 24 hours. Cache and reuse the access token until it expires. Hubstaff does not rotate refresh tokens. They remain valid until they expire.

The token endpoint allows up to five refresh attempts per hour for each refresh token. The sixth attempt within the same one-hour window returns an HTTP 400 response with the following error:

{
  "error": "rate_limit"
}

Failed refresh attempts may also count toward the limit. Do not refresh the access token before every API request or repeatedly retry a failed refresh request.

Why am I receiving an “Invalid Authentication Request” error?

Confirm that the redirect_uri in the authorization request exactly matches one of the redirect URIs configured for the OAuth application.

The protocol, hostname, port, path, and trailing slash must match. For example, these are different redirect URIs:

• http://localhost:3000/hubstaff/oauth
• http://localhost:3000/hubstaff/oauth/callback

You can configure more than one redirect URI for an OAuth application.

What does the “nonce required” error mean?

Hubstaff uses OpenID Connect for OAuth application authentication. Each authorization request must include a unique nonce value to help prevent replay attacks.

Make sure your application is configured to use OpenID Connect and sends a unique nonce with each authorization request. See the OAuth application documentation for the required parameters.

How can I retrieve tracked time or time entries?

Hubstaff does not currently provide a GET endpoint that returns tracked time as the same start-and-stop sessions shown in the Hubstaff web application. The Time Entries endpoints are used to add manual time.

For reporting totals, use the daily Activities endpoint. It returns pre-aggregated daily data and is generally more efficient than retrieving raw activities.

If you need exact start and stop times, use the raw Activities endpoint and reconstruct the sessions:

1. Retrieve the activity records for the required users and date range.
2. Group consecutive records while the user, project, and task remain the same.
3. Start a new session when there is a gap or the user, project, or task changes.
4. Calculate the end of an activity record by adding its tracked value, in seconds, to starts_at.

The API returns raw activities in 10-minute blocks, matching the data displayed under Activity > Screenshots. Each record includes values such as starts_at, tracked, keyboard, mouse, overall, project_id, and task_id.

How can I retrieve time logged to a task?

Use the organization Activities endpoint and filter the request using task_ids. You can retrieve raw 10-minute activity records or daily aggregated activities.

For reporting purposes, use daily activities when possible because the data is already aggregated by organization day and typically requires fewer API requests.

See the Activities API documentation for the available endpoints and filters.

How can I calculate activity levels from API data?

Raw activity records include:

• keyboard: Seconds with keyboard activity.
• mouse: Seconds with mouse activity.
• overall: Seconds with keyboard or mouse activity.
• tracked: Total seconds tracked in the activity block.
• input_tracked: Tracked seconds for which keyboard and mouse activity could be captured.

For an individual raw activity block where input tracking is enabled, calculate the activity percentage using:

(overall / tracked) × 100

When combining multiple records, calculate the weighted activity percentage using:

(sum of overall / sum of input_tracked) × 100

Using the summed values prevents short activity blocks from having the same weight as longer blocks and excludes time from tracking sources that cannot capture keyboard or mouse input.

Manual time, work breaks, mobile app time, web timer time, and time tracked when activity recording is disabled are not included in activity-level calculations. For more information, see How are activity levels calculated in Hubstaff?

Why can’t I create, update, or delete a task using the Hubstaff API v2?

You may receive an error similar to:

{
  "code": "invalid_params",
  "error": "Can not create a task for a project with a task integration",
  "error_code": 11000
}

The task creation, update, and deletion endpoints in Hubstaff API v2 are intended for simple to-dos. They cannot be used to manage tasks in a project connected to Hubstaff Tasks or a third-party task integration, such as Asana, Trello, or Jira.

If the project uses Hubstaff Tasks, use the Hubstaff Tasks API instead.

The Hubstaff API v2 task endpoints can still be used to retrieve tasks associated with a project, including tasks originating from supported integrations.

What should I do if the API rate limit is reached?

The default API rate limit is 1,000 requests per hour. When the limit is reached, the API returns an HTTP 429 Too Many Requests response. Before requesting a higher limit, review and optimize how your integration makes requests:

• Use the maximum supported page_limit of 500 where applicable.
• Cache member, user, project, and other information that does not change frequently.
• Use include parameters when an endpoint can return related records in the same response.
• Use daily Activities endpoints instead of raw Activities endpoints when aggregated reporting data meets your needs.
• Use webhooks instead of frequent polling when the required event is supported.
• Honor the Retry-After header before retrying a request.

For more information, see the pagination and rate-limit documentation.

If the limit is still reached after the workflow has been optimized, email api@hubstaff.com. Include your use case, the affected endpoints, approximate request volume, how often requests are made, and the optimizations already implemented.

We review rate-limit increase requests individually and cannot guarantee approval. We generally reserve rate-limit increases for Enterprise organizations when there is a demonstrated need, although exceptions may be considered.

How can I retrieve all organization members and their user details?

Use the organization Members endpoint:

GET /v2/organizations/{organization_id}/members

Where supported, use the include parameter to return related user information in the same response. This reduces the number of API requests required.

If additional user details are needed, retrieve them through the Users endpoint and cache the results whenever possible.

See the Members and Users API documentation.

Why does API data not match the Time and Activity report?

Detailed activity timestamps are returned in UTC. If you need data for a specific local date, convert the date range to UTC or provide the appropriate timezone.

The time_slot[stop] filter is exclusive. To retrieve one complete day, use the start of the day as time_slot[start] and the start of the following day as time_slot[stop]. You do not need to change the stop time to 23:59:59.

For report-style totals, use the daily Activities endpoint. Daily activities are aggregated using the organization’s timezone and generally align more closely with the Time & Activity report.

Previously retrieved totals may change when:

• Manual time is added.
• Tracked time is edited or deleted.
• Offline activity is uploaded later.
• Other changes are made after the original API request.

If your integration stores daily activity data, use the daily activity updates endpoint to identify and reconcile records that changed after the previous synchronization.

Does Hubstaff support webhooks?

Yes. Webhooks allow Hubstaff to notify your application when supported events occur, reducing the need to poll the API repeatedly.

Review the Webhooks API documentation for the currently supported events and payloads.

Store the webhook ID returned when a webhook is created. Hubstaff does not currently provide an endpoint to list existing webhooks, and the ID is required to update or delete a webhook.

Where can I get help with a Hubstaff API question?

For all API-related questions, including troubleshooting and rate-limit increase requests, email api@hubstaff.com.

When reporting an API issue, include:

• The request method and URL.
• Sanitized request parameters or request body.
• The HTTP status code and complete error response.
• The approximate request timestamp and timezone.
• The result you expected.

Do not include Client Secrets, access tokens, refresh tokens, organization access tokens, or other credentials.