Tracked time as 10-minute activity blocks and daily aggregates, with keyboard/mouse activity percentages.
openapi: 3.0.3
info:
title: Hubstaff Activities API
description: 'The Hubstaff API v2 provides programmatic read and write access to Hubstaff''s time tracking, timesheet, workforce management, and project management data - organizations, members, teams, projects, tasks, clients, activities (10-minute tracked time blocks with activity percentages), daily activity aggregates, time entries, timesheets and approvals, time off requests/policies/balances, attendance schedules and shifts, screenshots, app and URL usage, invoices, team payments, and webhooks.
Authentication uses OpenID Connect / OAuth 2.0 through Hubstaff Account (https://account.hubstaff.com). For server-side scripts, create a personal access token at https://developer.hubstaff.com/personal_access_tokens - the PAT acts as an OAuth refresh token (90-day expiry) that you exchange for short-lived access tokens at https://account.hubstaff.com/access_tokens. Send the access token as a Bearer token on every request.
Rate limit: authenticated users are allowed 1,000 requests per hour per application; individual requests time out after 30 seconds. All requests must use HTTPS. Collection endpoints use cursor pagination via page_start_id and page_limit. This document is a curated OpenAPI 3.0 rendering of the live Swagger 2.0 definition published at https://api.hubstaff.com/v2/docs, covering the primary resource areas; consult the live definition for the complete surface (insights, job sites, budgets, overtime policies, integrations, and more).'
version: '2.0'
contact:
name: Hubstaff Developer Portal
url: https://developer.hubstaff.com/
termsOfService: https://hubstaff.com/terms
servers:
- url: https://api.hubstaff.com
description: Hubstaff production API (paths include the /v2 prefix)
security:
- oauth2:
- hubstaff:read
- personalAccessToken: []
tags:
- name: Activities
description: Tracked time as 10-minute activity blocks and daily aggregates, with keyboard/mouse activity percentages.
paths:
/v2/organizations/{organization_id}/activities:
get:
operationId: getV2OrganizationsOrganizationIdActivities
tags:
- Activities
summary: List organization activities
description: 'Returns a collection of activities (10-minute time blocks) for the given organization.
Results can be filtered by user, task, project, and time range (time_slot[start], time_slot[stop]).
For aggregated daily data, use the daily_activities endpoint instead.
Note: Data may be delayed up to 20 minutes.
Note: Date range limit is 7 days. Earliest date is 6 months ago.'
parameters:
- name: organization_id
in: path
required: true
schema:
type: integer
format: int32
- name: page_start_id
in: query
description: The page start ID.
schema:
type: integer
format: int32
default: 0
- name: page_limit
in: query
description: The default page size
schema:
type: integer
format: int32
default: null
- name: time_slot[start]
in: query
description: Start time (ISO 8601)
required: true
schema:
type: string
format: date-time
- name: time_slot[stop]
in: query
description: Stop time (ISO 8601, Exclusive)
required: true
schema:
type: string
format: date-time
- name: user_ids
in: query
description: List of user IDs
schema:
type: array
items:
type: integer
format: int32
- name: task_ids
in: query
description: List of task IDs
schema:
type: array
items:
type: integer
format: int32
- name: global_todo_ids
in: query
description: List of global todo IDs
schema:
type: array
items:
type: integer
format: int32
- name: project_ids
in: query
description: List of project IDs
schema:
type: array
items:
type: integer
format: int32
- name: include
in: query
description: Specify related data to side load.
schema:
type: array
items:
type: string
enum:
- users
- projects
- tasks
- name: time_zone
in: query
description: The time zone name for the activity
schema:
type: string
responses:
'200':
description: A list of activities
'400':
description: Invalid parameters
'401':
description: Unauthorized
'403':
description: API access is only for organizations on an active plan
'404':
description: Could not find record
'429':
description: Rate limit exceeded
/v2/organizations/{organization_id}/activities/daily:
get:
operationId: getV2OrganizationsOrganizationIdActivitiesDaily
tags:
- Activities
summary: List organization daily activities
description: 'Returns daily aggregated time tracking data for the given organization.
Results can be filtered by user_ids[], task_ids[], project_ids[], and date[start]/[stop]. Data is aggregated by organization timezone date.
Note: Date range limit is 31 days. Earliest date is 3 years ago.'
parameters:
- name: organization_id
in: path
required: true
schema:
type: integer
format: int32
- name: page_start_id
in: query
description: The page start ID.
schema:
type: integer
format: int32
default: 0
- name: page_limit
in: query
description: The default page size
schema:
type: integer
format: int32
default: null
- name: date[start]
in: query
description: Start date (ISO 8601)
required: true
schema:
type: string
format: date
- name: date[stop]
in: query
description: Stop date (ISO 8601, Inclusive)
required: true
schema:
type: string
format: date
- name: user_ids
in: query
description: List of user IDs
schema:
type: array
items:
type: integer
format: int32
- name: task_ids
in: query
description: List of task IDs
schema:
type: array
items:
type: integer
format: int32
- name: project_ids
in: query
description: List of project IDs
schema:
type: array
items:
type: integer
format: int32
- name: include
in: query
description: Specify related data to side load.
schema:
type: array
items:
type: string
enum:
- users
- projects
- tasks
responses:
'200':
description: A list of daily activities
'400':
description: Invalid parameters
'401':
description: Unauthorized
'403':
description: API access is only for organizations on an active plan
'404':
description: Could not find record
'429':
description: Rate limit exceeded
/v2/organizations/{organization_id}/last_activities:
get:
operationId: getV2OrganizationsOrganizationIdLastActivities
tags:
- Activities
summary: List organization last activities
description: Returns the most recent activity for each member in the organization.
parameters:
- name: organization_id
in: path
required: true
schema:
type: integer
format: int32
- name: page_start_id
in: query
description: The page start ID.
schema:
type: integer
format: int32
default: 0
- name: page_limit
in: query
description: The default page size
schema:
type: integer
format: int32
default: null
- name: include_removed
in: query
description: Include users that were removed
schema:
type: boolean
default: false
- name: include
in: query
description: Specify related data to side load.
schema:
type: array
items:
type: string
enum:
- users
- projects
- tasks
responses:
'200':
description: Last activities for members
'400':
description: Invalid parameters
'401':
description: Unauthorized
'403':
description: API access is only for organizations on an active plan
'404':
description: Could not find record
'429':
description: Rate limit exceeded
/v2/projects/{project_id}/activities:
get:
operationId: getV2ProjectsProjectIdActivities
tags:
- Activities
summary: List project activities
description: 'Returns a collection of activities (10-minute time blocks) for the given project.
Results can be filtered by user, task, project, and time range (time_slot[start], time_slot[stop]).
For aggregated daily data, use the daily_activities endpoint instead.
Note: Data may be delayed up to 20 minutes.
Note: Date range limit is 7 days. Earliest date is 6 months ago.'
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
format: int32
- name: page_start_id
in: query
description: The page start ID.
schema:
type: integer
format: int32
default: 0
- name: page_limit
in: query
description: The default page size
schema:
type: integer
format: int32
default: null
- name: time_slot[start]
in: query
description: Start time (ISO 8601)
required: true
schema:
type: string
format: date-time
- name: time_slot[stop]
in: query
description: Stop time (ISO 8601, Exclusive)
required: true
schema:
type: string
format: date-time
- name: user_ids
in: query
description: List of user IDs
schema:
type: array
items:
type: integer
format: int32
- name: task_ids
in: query
description: List of task IDs
schema:
type: array
items:
type: integer
format: int32
- name: global_todo_ids
in: query
description: List of global todo IDs
schema:
type: array
items:
type: integer
format: int32
- name: include
in: query
description: Specify related data to side load.
schema:
type: array
items:
type: string
enum:
- users
- tasks
- name: time_zone
in: query
description: The time zone name for the activity
schema:
type: string
responses:
'200':
description: A list of activities
'400':
description: Invalid parameters
'401':
description: Unauthorized
'403':
description: API access is only for organizations on an active plan
'404':
description: Could not find record
'429':
description: Rate limit exceeded
/v2/projects/{project_id}/activities/daily:
get:
operationId: getV2ProjectsProjectIdActivitiesDaily
tags:
- Activities
summary: List project daily activities
description: 'Returns daily aggregated time tracking data for the given project.
Results can be filtered by user_ids[], task_ids[], project_ids[], and date[start]/[stop]. Data is aggregated by organization timezone date.
Note: Date range limit is 31 days. Earliest date is 3 years ago.'
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
format: int32
- name: page_start_id
in: query
description: The page start ID.
schema:
type: integer
format: int32
default: 0
- name: page_limit
in: query
description: The default page size
schema:
type: integer
format: int32
default: null
- name: date[start]
in: query
description: Start date (ISO 8601)
required: true
schema:
type: string
format: date
- name: date[stop]
in: query
description: Stop date (ISO 8601, Inclusive)
required: true
schema:
type: string
format: date
- name: user_ids
in: query
description: List of user IDs
schema:
type: array
items:
type: integer
format: int32
- name: task_ids
in: query
description: List of task IDs
schema:
type: array
items:
type: integer
format: int32
- name: include
in: query
description: Specify related data to side load.
schema:
type: array
items:
type: string
enum:
- users
- tasks
responses:
'200':
description: A list of daily activities
'400':
description: Invalid parameters
'401':
description: Unauthorized
'403':
description: API access is only for organizations on an active plan
'404':
description: Could not find record
'429':
description: Rate limit exceeded
components:
securitySchemes:
oauth2:
type: oauth2
description: Hubstaff Account OpenID Connect / OAuth 2.0 authentication. Scopes are hubstaff:read and hubstaff:write.
flows:
authorizationCode:
authorizationUrl: https://account.hubstaff.com/authorizations/new
tokenUrl: https://account.hubstaff.com/access_tokens
scopes:
hubstaff:read: Read access to the Hubstaff API
hubstaff:write: Write access to the Hubstaff API
personalAccessToken:
type: http
scheme: bearer
description: Access token obtained by exchanging a personal access token (created at https://developer.hubstaff.com/personal_access_tokens) via the OAuth 2.0 refresh token grant at https://account.hubstaff.com/access_tokens. PATs expire after 90 days.
externalDocs:
description: Hubstaff API v2 reference (interactive)
url: https://developer.hubstaff.com/docs/hubstaff_v2