Package 'togglr'

Title: Client for the 'Toggl Track' API
Description: Read and write time entries, projects and clients of the 'Toggl Track' time tracker <https://toggl.com> from R, and download its reports. Reads never return silently truncated or empty results: HTTP errors are raised, the hourly quota and rate limits are respected, and paginated reports are checked for completeness.
Authors: Vincent Guyader [aut, cre], ThinkR [cph, fnd]
Maintainer: Vincent Guyader <[email protected]>
License: GPL-3
Version: 0.3.0.9000
Built: 2026-10-14 22:58:13 UTC
Source: https://github.com/ThinkR-open/togglr

Help Index

togglr: client for the 'Toggl Track' API

Description

Track time spent in R with the toggl.com timesheet: read and write time entries, projects and clients, and download reports.

Author(s)

vincent <[email protected]>

See Also

Useful links:

ask_toggl_api_token

Description

ask for the toggle api token

Usage

ask_toggl_api_token(msg = "toggl api token")

Arguments

msg

the message

Empty the cache of the reports

Description

Removes the periods stored by 'get_detailled_report(cache = TRUE)'.

Usage

clean_cache(cache_dir = toggl_cache_dir())

Arguments

cache_dir

folder of the cache

Examples

## Not run: 
clean_cache()

## End(Not run)

clean memoise cache (deprecated)

Description

Deprecated: togglr no longer memoises. Removes the cache folder of togglr 0.2.x (and the reports cache it contains). Use [clean_cache()].

Usage

clean_memoise_cache(
  memoise_cache_dir = getOption("togglr_memoise_dir", default =
    rappdirs::user_cache_dir("togglr"))
)

Arguments

memoise_cache_dir

folder to remove

Examples

## Not run: 
clean_memoise_cache()

## End(Not run)

client_id_to_name

Description

return client name from client id

Usage

client_id_to_name(
  id,
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

id

client id
api_token

the toggl api token
workspace_id

workspace id

Value

the client name

client_name_to_id

Description

return client id from client name

Usage

client_name_to_id(
  name,
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

name

client name
api_token

the toggl api token
workspace_id

workspace id

Value

the client id

correct_date

Description

tricks to obtain iso 8601

Usage

correct_date(time)

Arguments

time

a POSIXt

Value

time in iso 8601

create_client

Description

create a client

Usage

create_client(
  name = "wihtout client",
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

name

client name
api_token

the toggl api token
workspace_id

workspace id

Value

the created client, as returned by the API (a list with its 'id')

Examples

## Not run: 
get_toggl_api_token()# set your api token here
create_client("new client")

## End(Not run)

delete_toggl_api_token

Description

delete the toggle api token

Usage

delete_toggl_api_token()

get_all_client_info

Description

get_all_client_info

Usage

get_all_client_info(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

api_token

the toggl api token
workspace_id

workspace_id

Value

a data.frame

Examples

## Not run: 
get_all_client_info()

## End(Not run)

get all client's name

Description

get all client's name

Usage

get_all_client_names(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today()
)

Arguments

api_token

the toggl api token
workspace_id

the workspace id
since

a date
until

a date

Get all project's names

Description

Get all project's names

Usage

get_all_project_names(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today()
)

Arguments

api_token

the toggl api token
workspace_id

the workspace id
since

a date
until

a date

get_client_project

Description

get_client_project

Usage

get_client_project(
  id,
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

id

client id
api_token

the toggl api token
workspace_id

workspace_id

Value

the client name

get_context

Description

retrieve Rstudio projet if possible

Usage

get_context()

get_context_projet

Description

retrieve Rstudio projet if possible

Usage

get_context_project()

get_current

Description

retrieve current projet id

Usage

get_current(api_token = get_toggl_api_token())

Arguments

api_token

the toggl api token

get current duration

Description

get current duration

Usage

get_current_duration(api_token = get_toggl_api_token())

Arguments

api_token

the Token API

Value

a difftime

Examples

## Not run: 
get_current_duration()

## End(Not run)

get all task from a project

Description

get all task from a project

Usage

get_current_project_task_detail(
  project_name = get_context_project(),
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today(),
  humain = TRUE
)

Arguments

project_name

project name
api_token

the toggl api token
workspace_id

the workspace id
since

a date
until

a date
humain

boolean humain readable time

get all data from <https://toggl.com>

Description

get all data from <https://toggl.com>

Usage

get_dashboard(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today()
)

Arguments

api_token

the toggl api token
workspace_id

the workspace id
since

begin date
until

stop date

Detailled report: every time entry of a period

Description

Downloads the time entries of the workspace between 'since' and 'until' (both included) from the reports API v2, all pages included.

Usage

get_detailled_report(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today(),
  user_agent = toggl_user_agent(),
  max_page = NULL,
  cache = FALSE,
  cache_dir = toggl_cache_dir(),
  memoise_cache_dir = NULL
)

Arguments

api_token

the toggl api token
workspace_id

the workspace id
since

begin date (included): a 'Date', a date-time or a text "AAAA-MM-JJ"; one year ago by default
until

end date (included), same formats; today by default
user_agent

user agent sent to the reports API
max_page

deprecated, ignored: the number of pages is now computed from the 'total_count' returned by the API.
cache

logical. If 'TRUE', a period fully fetched and checked is stored on disk and returned as is by later calls with the same 'since' / 'until'. Only use it for closed periods: entries created or edited later in Toggl will not be seen. Failures are never cached. Default 'FALSE'.
cache_dir

folder of the cache used when 'cache = TRUE': by default 'options("togglr.cache_dir")', or the 'reports' sub-folder of 'rappdirs::user_cache_dir("togglr")'
memoise_cache_dir

deprecated, use 'cache_dir'

Details

Columns: 'id', 'pid', 'tid', 'uid', 'description', 'start', 'end', 'updated' (text, ISO 8601), 'dur' (milliseconds), 'user', 'use_stop', 'client', 'project', 'project_color', 'project_hex_color', 'task', 'billable', 'is_billable', 'cur', 'tags' (list), then any column added by the API.

All the pages of the period are fetched, then the number of distinct entries is checked against the 'total_count' announced by the API. If entries are added, removed or edited while paginating (detected by a change of 'total_count' or of the total duration 'total_grand' returned with each page), the period is fetched again, up to 'options(togglr.report_attempts)' reads in all (3 by default); if the result is still incomplete, an error is raised. An HTTP error (quota, server error, authentication) raises an error too: the function never returns a silently truncated period.

Periods longer than a year (365 days or more between 'since' and 'until', across a new year) are split by calendar year.

Value

a tibble, one row per time entry, with fixed column types (see Details); 0 rows for an empty period

get_project_id

Description

retrieve project id

Usage

get_project_id(
  project_name = get_context_project(),
  api_token = get_toggl_api_token(),
  create = FALSE,
  client = NULL,
  workspace_id = get_workspace_id(api_token),
  color = NULL
)

Arguments

project_name

the project name
api_token

the toggl api token
create

boolean do you want to create the project if it doesnt exist ?
client

client name
workspace_id

workspace id
color

id of the color selected for the project

get_project_id_and_name

Description

retrieve project id and name

Usage

get_project_id_and_name(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

api_token

the toggl api token
workspace_id

workspace id

get project total time

Description

get project total time

Usage

get_project_total(
  project_name = get_context_project(),
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today()
)

Arguments

project_name

project name
api_token

the toggl api token
workspace_id

the workspace id
since

a date
until

a date

get summary report

Description

by user then projet

Usage

get_summary_report(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today(),
  user_agent = toggl_user_agent(),
  users = get_workspace_users(api_token = api_token, workspace_id = workspace_id)
)

Arguments

api_token

the toggl api token
workspace_id

the workspace id
since

begin date
until

stop date
user_agent

user_agent
users

users

Get all time entries between 2 dates

Description

Get all time entries between 2 dates

Usage

get_time_entries(
  api_token = get_toggl_api_token(),
  since = Sys.time() - lubridate::weeks(1),
  until = Sys.time(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

api_token

the toggl api token
since

begin date (One week ago by default)
until

stop date (Now by defaut)
workspace_id

the workspace id (to name the projects)

Value

a data.frame containing all time entries

Examples

## Not run: 
get_time_entries()

## End(Not run)

get_toggl_api_token

Description

return the toggle api token

Usage

get_toggl_api_token(ask = TRUE)

Arguments

ask

booleen do we have to ask if missing

get weekly report

Description

get weekly report

Usage

get_weekly_report(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  since = toggl_today() %m-% lubridate::years(1),
  until = toggl_today(),
  user_agent = toggl_user_agent()
)

Arguments

api_token

the toggl api token
workspace_id

the workspace id
since

begin date
until

stop date
user_agent

user_agent

get_workspace_id

Description

Return the workspace id

Usage

get_workspace_id(api_token = get_toggl_api_token())

Arguments

api_token

the toggl api token

Title

Description

Title

Usage

get_workspace_users(
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

api_token

the toggl api token
workspace_id

the workspace id

show notification

Description

show notification using message

Usage

notification(title, msg)

Arguments

title

title of the notificatin
msg

content of the notification

open toggle.com website on timesheet page

Description

open toggle.com website on timesheet page

Usage

open_toggl_website_app()

open toggle.com website on profile page

Description

open toggle.com website on profile page

Usage

open_toggl_website_profile()

set_toggl_api_token

Description

set the toggle api token

Usage

set_toggl_api_token(token)

Arguments

token

toggl api token

Simplify a parsed JSON answer into vectors and data frames

Description

Same result as 'jsonlite::fromJSON(simplifyVector = TRUE)' on a list already parsed with 'simplifyVector = FALSE' (what 'httr::content()' returns), using only the public API of jsonlite: the list is serialised back to JSON at full precision, then read with simplification.

Usage

simplify(x, ...)

Arguments

x

a list, as returned by 'httr::content()'
...

passed to 'jsonlite::fromJSON()' (e.g. 'simplifyDataFrame')

Value

the simplified object

transforme time column into humain readable column

Description

transforme time column into humain readable column

Usage

to_humain(df)

Arguments

df

a data.frame

toggl_create

Description

create a time entry

Usage

toggl_create(
  description = get_context(),
  start = now(),
  pid = get_project_id(api_token = api_token, workspace_id = workspace_id),
  stop,
  duration,
  tags = NULL,
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

description

the task you did
start

time in POSIXt
pid

pid
stop

time in POSIXt
duration

in seconds
tags

tags
api_token

the toggl api token
workspace_id

workspace id

Examples

## Not run: 
options(toggl_api_token = "XXXXXXXX")# set your toggl api token here
toggl_create(duration=1200)

toggl_create( description="description",
             start=now(),
             pid = get_project_id(project_name = "projectname",
                                 create=TRUE,client = "client"),
             duration=1000,
             api_token=get_toggl_api_token())





## End(Not run)

toggl_create_project

Description

create a project

Usage

toggl_create_project(
  project_name = get_context_project(),
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token),
  client = NULL,
  private = FALSE,
  color = NULL,
  active = TRUE
)

Arguments

project_name

project name
api_token

the toggl api token
workspace_id

workspace_id
client

client name: an existing client is reused, an unknown one is created; 'NULL' or '""' for no client
private

whether project is accessible for only project users or for all workspace users (boolean, default false)
color

color of the project, as a hex code (e.g. "#06aaf5")
active

boolean set project as active, TRUE by default

Value

the id of the project (created, or already existing)

Examples

## Not run: 
toggl_create_project()

## End(Not run)

toggl_start

Description

start a task

Usage

toggl_start(
  description = get_context(),
  client = "without client",
  project_name = get_context_project(),
  start = now(),
  api_token = get_toggl_api_token(),
  tags = "",
  workspace_id = get_workspace_id(api_token)
)

Arguments

description

the task you are doing
client

client name
project_name

nom du projet
start

start time in POSIXt
api_token

the toggl api token
tags

tags
workspace_id

workspace id

Examples

## Not run: 
get_toggl_api_token()# set your api token here
toggl_start()

## End(Not run)

toggl_stop

Description

stop the active task

Usage

toggl_stop(
  current = get_current(api_token = api_token),
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

current

list task id and start time
api_token

the toggl api token
workspace_id

workspace id

Examples

## Not run: 
options(toggl_api_token = "XXXXXXXX")# set your api token here
toggl_start()
toggl_stop()

## End(Not run)

toggl_update_entries

Description

update time entries

Usage

toggl_update_entries(
  time_entry_ids,
  description = NULL,
  start = NULL,
  pid = NULL,
  stop = NULL,
  duration = NULL,
  tags = NULL,
  api_token = get_toggl_api_token(),
  workspace_id = get_workspace_id(api_token)
)

Arguments

time_entry_ids

id(s) of time entries to update: one PUT request is sent per entry
description

the task you did
start

time in POSIXt
pid

project id
stop

time in POSIXt
duration

in seconds
tags

tags
api_token

the toggl api token
workspace_id

workspace id

Value

the updated entry, as returned by the API, or a list of them when several ids are given

Examples

## Not run: 
options(toggl_api_token = "XXXXXXXX")# set your toggl api token here
time_entry_id <- toggl_create(duration=1200)

toggl_update_entries( time_entry_id,
                    description = "new description",
                    duration = 100,
                    tags = c("tag1", "tag2"),
                    api_token=get_toggl_api_token())


## End(Not run)

update_toggl_api_token

Description

update the toggle api token

Usage

update_toggl_api_token()