The Timely connector lets your AI agent act in each user's Timely account. Each user signs in to Timely once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 53 tools.
- Tools
- 53
- What they doRead · write · destructive
- 31 · 16 · 631 read16 write6 destructive
- Users sign in with
- OAuth
- OAuth app
- Your own Timely app
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Timely connection
In AgentKit > Connections, create a Timely connection and copy its redirect URI. The name you give it is the
connection_nameyour code passes. See Configure connections.Register an OAuth app
Timely connections use your own OAuth app. Register one with Timely and add the redirect URI you copied.
Then enter the app's Client ID and Client Secret on the Timely connection.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'timely'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Timely:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'timely_list_accounts',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "timely"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Timely:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="timely_list_accounts",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_tooltimely_filter_reportsRun a filtered Timely report grouped by client, user, tag, day, or team.Read-onlyFilter Reports
Run a filtered Timely report grouped by client, user, tag, day, or team. Returns aggregated totals, or individual entries when scope is events. Use timely_get_report_totals for a simple per-client summary.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
billedstring- Filter by billed status: true or false.one of
truefalse client_idsstring- Comma-separated client IDs to include. Example: 4521,4522.
group_bystring- Comma-separated grouping keys from clients, users, labels, days, teams. Example: users,days.
label_idsstring- Comma-separated tag IDs to include. Example: 301,302.
project_idsstring- Comma-separated project IDs to include. Example: 98765,98766.
scopestring- Result scope: totals for aggregated data or events for individual entries.one of
totalsevents sincestring- Start date of the report period as YYYY-MM-DD. Example: 2026-10-01.
state_idsstring- Comma-separated time entry state IDs to include. Example: 12,13.
team_idsstring- Comma-separated team IDs to include. Example: 7001,7002.
untilstring- End date of the report period as YYYY-MM-DD. Example: 2026-10-31.
user_idsstring- Comma-separated user IDs to include. Example: 5001,5002.
timely_get_clientRetrieve one client in a Timely account by ID.Read-onlyGet Client
Retrieve one client in a Timely account by ID. Returns the client's name, color, active status, and external references. Use timely_list_clients to find the client ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the client. Get it from timely_list_clients. Example: 4521.
timely_get_complianceGet per-user time-logging compliance metrics for a Timely account over a date window.Read-onlyGet Compliance
Get per-user time-logging compliance metrics for a Timely account over a date window. Returns per-user and per-team compliance figures and the window used. Use for timesheet follow-up reviews.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
from_datestring- Inclusive start date as YYYY-MM-DD; defaults to 30 days before the end date. Example: 2026-09-15.
to_datestring- Inclusive end date as YYYY-MM-DD; defaults to today. Example: 2026-10-14.
timely_get_current_userRetrieve the connected user's own profile in a Timely account.Read-onlyGet Current User
Retrieve the connected user's own profile in a Timely account. Returns the user's id, name, email, role, and time zone. Use to learn the user_id for logging time as yourself.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
timely_get_insightsGet billable utilisation and where time went for a Timely account over a date window.Read-onlyGet Insights
Get billable utilisation and where time went for a Timely account over a date window. Returns logged, billable, non-billable and capacity minutes plus breakdowns by team or person, tag, and project. The team and organisation views need the matching Timely permissions.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
from_datestring- Inclusive start date as YYYY-MM-DD; defaults to 30 days before the end date. Example: 2026-09-15.
groupingstring- How to group the utilisation card: team or person.one of
teamperson project_scopestring- Narrow the by-project rows: all, billable or non_billable.one of
allbillablenon_billable tag_scopestring- Narrow the by-tag rows: all, billable or non_billable.one of
allbillablenon_billable to_datestring- Inclusive end date as YYYY-MM-DD; defaults to today. Example: 2026-10-14.
viewstring- Whose hours to report on: mine, team or organisation. Team and organisation need permissions.one of
mineteamorganisation
timely_get_linked_work_itemRetrieve one linked work item in a Timely account by ID.Read-onlyGet Linked Work Item
Retrieve one linked work item in a Timely account by ID. Returns the item's title, external code, url, project, assignee, and dates. Use timely_list_linked_work_items to find the item ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the linked work item. Get it from timely_list_linked_work_items. Example: 9901.
timely_get_projectRetrieve one project in a Timely account by ID.Read-onlyGet Project
Retrieve one project in a Timely account by ID. Returns the project's name, client, color, rates, budget, assigned users, and status. Use timely_list_projects to find the project ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the project. Get it from timely_list_projects. Example: 98765.
timely_get_report_totalsGet aggregated time and cost totals for a Timely account over a date range.Read-onlyGet Report Totals
Get aggregated time and cost totals for a Timely account over a date range. Returns duration, cost, billed and unbilled totals per client with nested projects. Use timely_filter_reports for grouping, tag, team or state filters.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
client_idsstring- Comma-separated client IDs to include. Example: 4521,4522.
project_idsstring- Comma-separated project IDs to include. Example: 98765,98766.
sincestring- Start date of the report period as YYYY-MM-DD. Example: 2026-10-01.
untilstring- End date of the report period as YYYY-MM-DD. Example: 2026-10-31.
user_idsstring- Comma-separated user IDs to include. Example: 5001,5002.
timely_get_tagRetrieve one tag (label) in a Timely account by ID.Read-onlyGet Tag
Retrieve one tag (label) in a Timely account by ID. Returns the tag's name, parent, emoji, children, and active status. Use timely_list_tags to find the tag ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the tag. Get it from timely_list_tags. Example: 301.
timely_get_taskRetrieve one planned task (forecast) in a Timely account by ID.Read-onlyGet Task
Retrieve one planned task (forecast) in a Timely account by ID. Returns the task's title, dates, assignee, project, and estimated, planned, and logged duration. Use timely_list_tasks to find the task ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the task. Get it from timely_list_tasks. Example: 8801.
timely_get_task_summarySummarize planned tasks (forecasts) in a Timely account grouped by user or project.Read-onlyGet Task Summary
Summarize planned tasks (forecasts) in a Timely account grouped by user or project. Returns task count plus estimated, planned, and logged totals per group. Use timely_list_tasks for the individual tasks.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
resourcestringrequired- Grouping for the summary: users or projects.one of
usersprojects completedstring- Filter by completion status: true or false.one of
truefalse project_idsstring- Comma-separated project IDs to include. Example: 98765,98766.
sincestring- Only tasks from this date as YYYY-MM-DD. Example: 2026-10-01.
untilstring- Only tasks up to this date as YYYY-MM-DD. Example: 2026-10-31.
user_idsstring- Comma-separated user IDs to include. Example: 5001,5002.
timely_get_teamRetrieve one team in a Timely account by ID.Read-onlyGet Team
Retrieve one team in a Timely account by ID. Returns the team's name, color, members, and project IDs. Use timely_list_teams to find the team ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the team. Get it from timely_list_teams. Example: 7001.
timely_get_time_entryRetrieve one time entry in a Timely account by ID.Read-onlyGet Time Entry
Retrieve one time entry in a Timely account by ID. Returns the entry's day, duration, note, project, user, tags, rates, and timer state. Use timely_list_time_entries to find the entry ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the time entry. Get it from timely_list_time_entries. Example: 55501.
timely_get_userRetrieve one user in a Timely account by ID.Read-onlyGet User
Retrieve one user in a Timely account by ID. Returns the user's name, email, role, time zone, and capacity settings. Use timely_list_users to find the user ID.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the user. Get it from timely_list_users. Example: 5001.
timely_get_user_capacitiesList the working-capacity periods for one Timely user.Read-onlyGet User Capacities
List the working-capacity periods for one Timely user. Returns weekly and daily capacity, working days, and the start and end date of each period. Use timely_list_user_capacities to compare several users.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
user_idintegerrequired- ID of the user. Get it from timely_list_users. Example: 5001.
timely_list_accountsList the Timely accounts (workspaces) the connected user belongs to.Read-onlyList Accounts
List the Timely accounts (workspaces) the connected user belongs to. Returns account id, name, and plan details for each account. Use first to get the account_id every other Timely tool requires.
Inputs
This tool takes no inputs.
timely_list_clientsList clients in a Timely account.Read-onlyList Clients
List clients in a Timely account. Returns each client's id, name, color, and active status. Use timely_get_client for one client.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
limitinteger- Maximum number of clients to return. Example: 50.
offsetinteger- Number of clients to skip, for paging through results. Example: 0.
orderstring- Sort order: asc (default) or desc.one of
ascdesc showstring- Which clients to return: all, active or archived.one of
allactivearchived
timely_list_current_user_permissionsList the connected user's permissions in a Timely account.Read-onlyList Current User Permissions
List the connected user's permissions in a Timely account. Returns each resource with the permissions the user holds on it. Use to check what the connected user may do before attempting a write.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
timely_list_day_propertiesList per-day properties such as locked days in a Timely account.Read-onlyList Day Properties
List per-day properties such as locked days in a Timely account. Returns each date with its user, locked flag, and timestamps. Use to check whether a day is locked before logging time.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
datesstring- Comma-separated specific dates as YYYY-MM-DD. Example: 2026-10-14,2026-10-15.
sincestring- Start date as YYYY-MM-DD. Example: 2026-10-01.
untilstring- End date as YYYY-MM-DD. Example: 2026-10-31.
timely_list_linked_work_itemsList linked work items (tickets or tasks from external systems) in a Timely account.Read-onlyList Linked Work Items
List linked work items (tickets or tasks from external systems) in a Timely account. Returns each item's id, title, external code, url, project, assignee, and dates. Use timely_get_linked_work_item for one item.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
assigned_user_idinteger- Only items assigned to this user ID. Example: 5001.
external_idstring- Only the item with this exact external_id. Example: 10042.
limitinteger- Maximum number of items to return. Example: 50.
offsetinteger- Number of items to skip, for paging through results. Example: 0.
project_idinteger- Only items for this project ID. Example: 98765.
searchstring- Search by title or external code. Example: login.
statusstring- Filter by status: open or completed.one of
opencompleted
timely_list_projectsList projects in a Timely account, optionally filtered by state or relation to the user.Read-onlyList Projects
List projects in a Timely account, optionally filtered by state or relation to the user. Returns project id, name, client, color, rate, budget, and active status. Use timely_get_project for one project in full.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
limitinteger- Maximum number of projects to return. Example: 50.
offsetinteger- Number of projects to skip, for paging through results. Example: 0.
orderstring- Sort order by creation: asc or desc (Timely default is desc).one of
ascdesc relationstring- Filter by the user's relation to the project: assigned, created or all.one of
allassignedcreated statestring- Filter by project state: active, archived or all.one of
allactivearchived totalsboolean- Include per-project cost and duration totals (true by default). Set false for a faster, lighter response.
updated_afterstring- Only return projects updated after this timestamp. Example: 2026-01-01T00:00:00Z.
timely_list_rolesList the user roles defined in a Timely account.Read-onlyList Roles
List the user roles defined in a Timely account. Returns each role's id, name, description, and permission scopes. Use to see which roles users can hold.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
timely_list_statesList the time entry states (such as billed or locked) defined in a Timely account.Read-onlyList States
List the time entry states (such as billed or locked) defined in a Timely account. Returns each state's id, name, color, and billed and locked flags. Use to get state IDs for timely_create_time_entry.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
timely_list_tasksList planned tasks (forecasts) in a Timely account, filtered by date, user, project, or completion.Read-onlyList Tasks
List planned tasks (forecasts) in a Timely account, filtered by date, user, project, or completion. Returns each task's id, title, dates, assignee, project, and estimated and logged duration. Use timely_get_task for one task.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
completedstring- Filter by completion status: true or false.one of
truefalse orderstring- Sort direction: asc or desc.one of
ascdesc pageinteger- Page number, starting at 1. Example: 1.
per_pageinteger- Results per page, up to 5000. Example: 100.
project_idsstring- Comma-separated project IDs, or active or archived. Example: 98765,98766.
sincestring- Only tasks from this date as YYYY-MM-DD, inclusive. Example: 2026-10-01.
sortstring- Field to sort by: updated_at, created_at, from or to.one of
updated_atcreated_atfromto uptostring- Only tasks up to this date as YYYY-MM-DD, inclusive. Example: 2026-10-31.
user_idsstring- Comma-separated user IDs to include. Example: 5001,5002.
timely_list_teamsList teams in a Timely account.Read-onlyList Teams
List teams in a Timely account. Returns each team's id, name, color, member user IDs, and project IDs. Use timely_search_teams to find a team by name.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
filterstring- Set to mine to only list teams the connected user belongs to.one of
mine limitinteger- Maximum number of teams to return. Example: 50.
offsetinteger- Number of teams to skip, for paging through results. Example: 0.
orderstring- Sort order: asc (default) or desc.one of
ascdesc
timely_list_time_entriesList time entries in a Timely account, filtered by date range, project, or user.Read-onlyList Time Entries
List time entries in a Timely account, filtered by date range, project, or user. Returns each entry's id, day, duration, note, project, user, and tags. Use timely_get_time_entry for one entry in full.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
daystring- Return entries for one date as YYYY-MM-DD; ignored when since and upto are set. Timely defaults to today. Example: 2026-10-14.
orderstring- Sort direction: asc or desc.one of
ascdesc pageinteger- Page number, starting at 1. Example: 1.
per_pageinteger- Results per page, up to 5000. Example: 100.
project_idinteger- Only return entries for this project ID. Example: 98765.
sincestring- Start date of the range as YYYY-MM-DD, inclusive. Must be given together with upto. Example: 2026-10-01.
sortstring- Field to sort by: day, created_at or updated_at.one of
daycreated_atupdated_at uptostring- End date of the range as YYYY-MM-DD, inclusive. Must be given together with since. Example: 2026-10-31.
user_idinteger- Only return entries for this user ID. Example: 5001.
timely_list_user_capacitiesList working-capacity periods for multiple Timely users.Read-onlyList User Capacities
List working-capacity periods for multiple Timely users. Returns each user's id with their capacity periods. Use timely_get_user_capacities for a single user.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
sincestring- Only capacities after this date as YYYY-MM-DD. Example: 2026-10-01.
untilstring- Only capacities before this date as YYYY-MM-DD. Example: 2026-10-31.
user_idsstring- Comma-separated user IDs to include. Example: 5001,5002.
timely_list_usersList users in a Timely account.Read-onlyList Users
List users in a Timely account. Returns each user's id, name, email, role, time zone, and active status. Use timely_search_users to find a user by name or email.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
filterstring- Set to deleted to list deleted users instead of active ones.one of
deleted limitinteger- Maximum number of users to return. Example: 50.
offsetinteger- Number of users to skip, for paging through results. Example: 0.
orderstring- Sort order: asc or desc.one of
ascdesc
timely_search_teamsSearch teams in a Timely account by name.Read-onlySearch Teams
Search teams in a Timely account by name. Returns matching teams with id, name, color, and members. Use timely_list_teams to browse every team.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
pageinteger- Page number, starting at 1. Example: 1.
per_pageinteger- Results per page. Example: 25.
qstring- Search text matched against team names. Example: design.
timely_search_usersSearch users in a Timely account by name or email.Read-onlySearch Users
Search users in a Timely account by name or email. Returns matching users with id, name, email, and active status. Use timely_list_users to browse every user.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
qstringrequired- Search text matched against user names and emails. Example: jane.
pageinteger- Page number, starting at 1. Example: 1.
per_pageinteger- Results per page. Example: 25.
timely_create_clientCreate a client in a Timely account.WriteCreate Client
Create a client in a Timely account. Returns the created client with its id and name. Use timely_update_client to change an existing client.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
activeboolean- Whether the client is active. Set false to archive it.
colorstring- Hex color for the client without the leading #. Example: FF5733.
namestring- Client name. Example: Acme Corp.
timely_create_linked_work_itemCreate a linked work item in a Timely account to mirror a ticket or task from an external system.WriteCreate Linked Work Item
Create a linked work item in a Timely account to mirror a ticket or task from an external system. Returns the created item with its id. Use timely_update_linked_work_item to change an existing item.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
assigned_user_idinteger- ID of the Timely user assigned to the item. Example: 5001.
completed_atstring- Completion timestamp in ISO 8601 format. Example: 2026-10-20T17:00:00Z.
descriptionstring- Description of the work item. Example: Users cannot log in with SSO.
due_datestring- Due date as YYYY-MM-DD. Example: 2026-10-21.
external_codestring- Short code from the source system. Example: JRA-123.
external_idstring- Your own unique ID for the item in the source system. Example: 10042.
project_idinteger- ID of the Timely project to associate. Example: 98765.
source_namestring- Name of the source system. Example: Jira.
start_datestring- Start date as YYYY-MM-DD. Example: 2026-10-14.
titlestring- Title of the work item. Example: Fix login bug.
urlstring- Link to the work item in the source system. Example: https://example.atlassian.net/browse/JRA-123.
timely_create_projectCreate a project in a Timely account.WriteCreate Project
Create a project in a Timely account. Returns the created project with its id, name, client, rates, and budget. Use timely_update_project to change an existing project.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
activeboolean- Whether the project is active. Set false to archive it.
billableboolean- Whether time logged to the project is billable by default.
budgetnumber- Budget amount, in hours or money depending on budget_type. Example: 120.
budget_typestring- Budget unit: H for hours or M for money.one of
HM client_idinteger- ID of the client the project belongs to. Get it from timely_list_clients. Example: 4521.
colorstring- Hex color for the project without the leading #, 3 or 6 characters. Example: 3366FF.
descriptionstring- Free-text project description. Example: Redesign of the marketing website.
external_idstring- Your own reference ID for this project, up to 512 characters. Example: JRA-123.
hour_ratenumber- Hourly rate for the project in the account currency. Example: 95.5.
namestring- Project name. Example: Website Redesign.
rate_typestring- How the hourly rate is applied: project (one rate), user (rate per user) or non-billable.one of
projectusernon-billable team_idsarray- IDs of teams to assign to the project. Get them from timely_list_teams. Example: [11, 12].
usersarray- Users to assign to the project, each as an object with user_id and hour_rate. Example: [{"user_id": 5001, "hour_rate": 80}].
timely_create_tagCreate a tag (label) in a Timely account.WriteCreate Tag
Create a tag (label) in a Timely account. Returns the created tag with its id and name. Use timely_update_tag to change an existing tag.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
activeboolean- Whether the tag is active. Set false to archive it.
emojistring- Emoji shown next to the tag. Example: 🎨.
external_idstring- Your own reference ID for this tag. Example: tag-design.
namestring- Tag name. Example: Design.
parent_idinteger- ID of a parent tag to nest this tag under. Get it from timely_list_tags. Example: 301.
timely_create_taskCreate a planned task (forecast) in a Timely account.WriteCreate Task
Create a planned task (forecast) in a Timely account. Returns the created task with its id, dates, and assignee. Use timely_update_task to change an existing task.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
completed_atstring- Completion timestamp in ISO 8601 format; set to mark the task done. Example: 2026-10-18T17:00:00Z.
descriptionstring- Task description. Example: Implement the new landing page design.
estimated_minutesinteger- Estimated effort in minutes. Example: 480.
external_idstring- Your own reference ID for this task. Example: PLAN-7.
from_datestring- Task start date as YYYY-MM-DD. Example: 2026-10-14.
label_idsarray- IDs of tags to apply to the task. Example: [301].
project_idinteger- ID of the project the task belongs to. Get it from timely_list_projects. Example: 98765.
titlestring- Task title. Example: Build landing page.
to_datestring- Task end date as YYYY-MM-DD. Example: 2026-10-18.
user_idinteger- ID of the user the task is assigned to. Get it from timely_list_users. Example: 5001.
timely_create_teamCreate a team in a Timely account.WriteCreate Team
Create a team in a Timely account. Returns the created team with its id and members. Use timely_update_team to change an existing team.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
colorstring- Hex color for the team without the leading #. Example: FF5733.
emojistring- Emoji for the team. Example: 🚀.
namestring- Team name. Example: Design Team.
usersarray- Team members, each as an object with user_id plus optional lead and hide_hours booleans. Example: [{"user_id": 5001, "lead": true}].
timely_create_time_entryLog a time entry in a Timely account against a project and day.WriteCreate Time Entry
Log a time entry in a Timely account against a project and day. Returns the created entry with its id, duration, project, and user. Use timely_update_time_entry to change an existing entry.
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
billableboolean- Whether the entry is billable.
billedboolean- Whether the entry has already been billed.
daystring- Date of the entry as YYYY-MM-DD. Example: 2026-10-14.
external_idstring- Your own reference ID for this entry. Example: TASK-42.
from_timestring- Start timestamp of the entry in ISO 8601 format. Example: 2026-10-14T09:00:00+00:00.
hour_ratenumber- Hourly rate for this entry. Example: 95.5.
hoursinteger- Whole hours of logged duration. Example: 2.
label_idsarray- IDs of tags to apply to the entry. Get them from timely_list_tags. Example: [301, 302].
minutesinteger- Minutes of logged duration, 0 to 59. Example: 30.
notestring- Description of the work done. Example: Drafted homepage wireframes.
project_idinteger- ID of the project the time is logged to. Get it from timely_list_projects. Example: 98765.
secondsinteger- Seconds of logged duration, 0 to 59. Example: 0.
state_idinteger- ID of the time entry state to set. Get it from timely_list_states. Example: 12.
to_timestring- End timestamp of the entry in ISO 8601 format. Example: 2026-10-14T11:30:00+00:00.
user_idinteger- ID of the user the entry belongs to; defaults to the connected user. Get it from timely_list_users. Example: 5001.
timely_start_timerStart the timer on an existing Timely time entry.WriteStart Timer
Start the timer on an existing Timely time entry. Returns the entry with its timer running. Use timely_stop_timer to stop it; create the entry with timely_create_time_entry first.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the time entry. Get it from timely_list_time_entries. Example: 55501.
timely_stop_timerStop the running timer on a Timely time entry.WriteStop Timer
Stop the running timer on a Timely time entry. Returns the entry with its final logged duration. Use after timely_start_timer.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the time entry. Get it from timely_list_time_entries. Example: 55501.
timely_update_clientUpdate fields on an existing Timely client; only the fields provided change.WriteUpdate Client
Update fields on an existing Timely client; only the fields provided change. Returns the updated client. Use timely_create_client to add a new client.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the client. Get it from timely_list_clients. Example: 4521.
activeboolean- Whether the client is active. Set false to archive it.
colorstring- Hex color for the client without the leading #. Example: FF5733.
namestring- Client name. Example: Acme Corp.
timely_update_linked_work_itemUpdate fields on an existing Timely linked work item; only the fields provided change.WriteUpdate Linked Work Item
Update fields on an existing Timely linked work item; only the fields provided change. Returns the updated item. Use timely_create_linked_work_item to add a new item.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the linked work item. Get it from timely_list_linked_work_items. Example: 9901.
assigned_user_idinteger- ID of the Timely user assigned to the item. Example: 5001.
completed_atstring- Completion timestamp in ISO 8601 format. Example: 2026-10-20T17:00:00Z.
descriptionstring- Description of the work item. Example: Users cannot log in with SSO.
due_datestring- Due date as YYYY-MM-DD. Example: 2026-10-21.
external_codestring- Short code from the source system. Example: JRA-123.
external_idstring- Your own unique ID for the item in the source system. Example: 10042.
project_idinteger- ID of the Timely project to associate. Example: 98765.
source_namestring- Name of the source system. Example: Jira.
start_datestring- Start date as YYYY-MM-DD. Example: 2026-10-14.
titlestring- Title of the work item. Example: Fix login bug.
urlstring- Link to the work item in the source system. Example: https://example.atlassian.net/browse/JRA-123.
timely_update_projectUpdate fields on an existing Timely project; only the fields provided change.WriteUpdate Project
Update fields on an existing Timely project; only the fields provided change. Returns the updated project. Use timely_create_project to add a new project.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the project. Get it from timely_list_projects. Example: 98765.
activeboolean- Whether the project is active. Set false to archive it.
billableboolean- Whether time logged to the project is billable by default.
budgetnumber- Budget amount, in hours or money depending on budget_type. Example: 120.
budget_typestring- Budget unit: H for hours or M for money.one of
HM client_idinteger- ID of the client the project belongs to. Get it from timely_list_clients. Example: 4521.
colorstring- Hex color for the project without the leading #, 3 or 6 characters. Example: 3366FF.
descriptionstring- Free-text project description. Example: Redesign of the marketing website.
external_idstring- Your own reference ID for this project, up to 512 characters. Example: JRA-123.
hour_ratenumber- Hourly rate for the project in the account currency. Example: 95.5.
namestring- Project name. Example: Website Redesign.
rate_typestring- How the hourly rate is applied: project (one rate), user (rate per user) or non-billable.one of
projectusernon-billable team_idsarray- IDs of teams to assign to the project. Get them from timely_list_teams. Example: [11, 12].
usersarray- Users to assign to the project, each as an object with user_id and hour_rate. Example: [{"user_id": 5001, "hour_rate": 80}].
timely_update_tagUpdate fields on an existing Timely tag; only the fields provided change.WriteUpdate Tag
Update fields on an existing Timely tag; only the fields provided change. Returns the updated tag. Use timely_create_tag to add a new tag.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the tag. Get it from timely_list_tags. Example: 301.
activeboolean- Whether the tag is active. Set false to archive it.
emojistring- Emoji shown next to the tag. Example: 🎨.
external_idstring- Your own reference ID for this tag. Example: tag-design.
namestring- Tag name. Example: Design.
parent_idinteger- ID of a parent tag to nest this tag under. Get it from timely_list_tags. Example: 301.
timely_update_taskUpdate fields on an existing Timely planned task; only the fields provided change.WriteUpdate Task
Update fields on an existing Timely planned task; only the fields provided change. Returns the updated task. Use timely_create_task to plan new work.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the task. Get it from timely_list_tasks. Example: 8801.
completed_atstring- Completion timestamp in ISO 8601 format; set to mark the task done. Example: 2026-10-18T17:00:00Z.
descriptionstring- Task description. Example: Implement the new landing page design.
estimated_minutesinteger- Estimated effort in minutes. Example: 480.
external_idstring- Your own reference ID for this task. Example: PLAN-7.
from_datestring- Task start date as YYYY-MM-DD. Example: 2026-10-14.
label_idsarray- IDs of tags to apply to the task. Example: [301].
project_idinteger- ID of the project the task belongs to. Get it from timely_list_projects. Example: 98765.
titlestring- Task title. Example: Build landing page.
to_datestring- Task end date as YYYY-MM-DD. Example: 2026-10-18.
user_idinteger- ID of the user the task is assigned to. Get it from timely_list_users. Example: 5001.
timely_update_teamUpdate fields on an existing Timely team; only the fields provided change.WriteUpdate Team
Update fields on an existing Timely team; only the fields provided change. Returns the updated team. Use timely_create_team to add a new team.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the team. Get it from timely_list_teams. Example: 7001.
add_users_to_team_projectsboolean- Whether new team members are also added to the team's projects.
colorstring- Hex color for the team without the leading #. Example: FF5733.
delete_users_from_team_projectsboolean- Whether removed team members are also removed from the team's projects.
emojistring- Emoji for the team. Example: 🚀.
namestring- Team name. Example: Design Team.
usersarray- Team members, each as an object with user_id plus optional lead and hide_hours booleans. Example: [{"user_id": 5001, "lead": true}].
timely_update_time_entryUpdate fields on an existing Timely time entry; only the fields provided change.WriteUpdate Time Entry
Update fields on an existing Timely time entry; only the fields provided change. Returns the updated entry. Use timely_create_time_entry to log new time.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the time entry. Get it from timely_list_time_entries. Example: 55501.
billableboolean- Whether the entry is billable.
billedboolean- Whether the entry has already been billed.
daystring- Date of the entry as YYYY-MM-DD. Example: 2026-10-14.
external_idstring- Your own reference ID for this entry. Example: TASK-42.
from_timestring- Start timestamp of the entry in ISO 8601 format. Example: 2026-10-14T09:00:00+00:00.
hour_ratenumber- Hourly rate for this entry. Example: 95.5.
hoursinteger- Whole hours of logged duration. Example: 2.
label_idsarray- IDs of tags to apply to the entry. Get them from timely_list_tags. Example: [301, 302].
minutesinteger- Minutes of logged duration, 0 to 59. Example: 30.
notestring- Description of the work done. Example: Drafted homepage wireframes.
project_idinteger- ID of the project the time is logged to. Get it from timely_list_projects. Example: 98765.
secondsinteger- Seconds of logged duration, 0 to 59. Example: 0.
state_idinteger- ID of the time entry state to set. Get it from timely_list_states. Example: 12.
to_timestring- End timestamp of the entry in ISO 8601 format. Example: 2026-10-14T11:30:00+00:00.
user_idinteger- ID of the user the entry belongs to; defaults to the connected user. Get it from timely_list_users. Example: 5001.
timely_delete_linked_work_itemPermanently delete a linked work item from a Timely account.DestructiveDelete Linked Work Item
Permanently delete a linked work item from a Timely account. Returns an empty success response. Use timely_update_linked_work_item to edit it instead.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the linked work item. Get it from timely_list_linked_work_items. Example: 9901.
timely_delete_projectPermanently delete a project from a Timely account.DestructiveDelete Project
Permanently delete a project from a Timely account. Returns an empty success response. Use timely_update_project with active=false to archive a project instead of deleting it.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the project. Get it from timely_list_projects. Example: 98765.
timely_delete_tagPermanently delete a tag (label) from a Timely account.DestructiveDelete Tag
Permanently delete a tag (label) from a Timely account. Returns an empty success response. Use timely_update_tag with active=false to archive a tag instead.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the tag. Get it from timely_list_tags. Example: 301.
timely_delete_taskPermanently delete a planned task (forecast) from a Timely account.DestructiveDelete Task
Permanently delete a planned task (forecast) from a Timely account. Returns an empty success response. Use timely_update_task with completed_at to mark a task done instead.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the task. Get it from timely_list_tasks. Example: 8801.
timely_delete_teamPermanently delete a team from a Timely account.DestructiveDelete Team
Permanently delete a team from a Timely account. Returns an empty success response. Use timely_update_team to rename or change members instead.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the team. Get it from timely_list_teams. Example: 7001.
delete_project_usersboolean- Whether to also remove the team's users from the team's projects.
timely_delete_time_entryPermanently delete a time entry from a Timely account.DestructiveDelete Time Entry
Permanently delete a time entry from a Timely account. Returns an empty success response. Use timely_update_time_entry to correct an entry instead of deleting it.
- Idempotent
Inputs
account_idintegerrequired- Timely account (workspace) ID that owns the data. Get it from timely_list_accounts. Example: 1234567.
idintegerrequired- ID of the time entry. Get it from timely_list_time_entries. Example: 55501.
No tools match.
