Guide

Pull Clockify time entries into Google Sheets with the API

Written against Clockify's published v1 reference and Google's Apps Script docs — every source is listed at the end of the page: auth header, endpoint choice, pagination, the fields you actually get, and the limits that bite on a Free workspace.

Step one

The three IDs you need first

The API key. Avatar → Preferences → Advanced → Manage API keys → Generate. Copy it at once; Clockify shows it one time. If your workspace is on a subdomain, the reference is explicit that the key must be generated from that subdomain. A Clockify key also cannot be made read-only, so admins should generate it from a member-level user.

The workspace and user IDs. No need to dig these out of the URL bar: GET /v1/user returns id (your user ID) alongside activeWorkspace and defaultWorkspace.

Code.gs — key storage and one fetch wrapper

const API = 'https://api.clockify.me/api/v1';

// Put the key in Project Settings → Script properties as CLOCKIFY_KEY.
// It never appears in this file, so it never lands in your repo.
function clockify_(url, payload) {
  const key = PropertiesService.getScriptProperties().getProperty('CLOCKIFY_KEY');
  if (!key) throw new Error('Add CLOCKIFY_KEY in Project Settings > Script properties.');

  const options = {
    method: payload ? 'post' : 'get',
    headers: { 'X-Api-Key': key },   // not Authorization: Bearer
    contentType: 'application/json',
    muteHttpExceptions: true         // so we can read the body of a 4xx
  };
  if (payload) options.payload = JSON.stringify(payload);

  const res  = UrlFetchApp.fetch(url, options);
  const code = res.getResponseCode();
  if (code === 429) {
    throw new Error('Rate limited. A Free workspace gets 30 requests per hour.');
  }
  if (code < 200 || code >= 300) {
    throw new Error('Clockify ' + code + ': ' + res.getContentText().slice(0, 300));
  }
  return { data: JSON.parse(res.getContentText()), headers: res.getAllHeaders() };
}

function whoAmI() {
  const me = clockify_(API + '/user').data;
  Logger.log('userId: %s   activeWorkspace: %s', me.id, me.activeWorkspace);
  return me;
}

Endpoint choice

reports/detailed or the time-entries endpoint?

Two ways to read time entries, and they are not interchangeable.

Reports are boxed in on Free. Clockify's Free-plan page states that the Report date range filter on the Free plan is now capped at a maximum of 1 month (31 days) per query. Its exportType accepts JSON, CSV, XLSX and PDF, but Clockify states that Export to CSV/Excel is a paid feature available in Basic plan or higher — so on Free, ask for JSON. Clockify's own example body uses "detailedFilter": { "page": 1, "pageSize": 1000 }, and 1000 is also the documented ceiling for report endpoints.

Importing your own hours? Use the user endpoint. Plain GET, no documented 31-day cap, no separate host. Reach for reports/detailed only when you need every user at once — then chunk into 31-day windows so one code path serves Free and paid.

Response shape

The fields you get back, mapped to sheet columns

The response is a bare array. Clockify's sample shows id, description, projectId, taskId, tagIds, userId, workspaceId, billable, isLocked, type, customFieldValues, hourlyRate, costRate, and timeInterval with start, end, duration.

The project name is what catches people. An entry gives you projectId and nothing else. The endpoint accepts a hydrated boolean, but the reference describes it only as a flag to set whether to include additional information on time entries or not and never documents the resulting shape — an undocumented response is a poor foundation. One extra call is safer: GET /v1/workspaces/{workspaceId}/projects returns id and name. It pages like every other list endpoint, so read all the pages before you trust the map.

Code.gs — resolving project IDs to names

function projectNames_(workspaceId) {
  const PAGE_SIZE = 200, map = {};

  for (let page = 1; page <= 20; page++) {
    const url = API + '/workspaces/' + workspaceId + '/projects'
      + '?page=' + page + '&page-size=' + PAGE_SIZE;   // paged like every list endpoint

    const batch = clockify_(url).data;
    batch.forEach(function (p) { map[p.id] = p.name; });
    if (batch.length < PAGE_SIZE) break;
  }
  return map;
}

Rate limits

30 per hour on Free, 50 per second on paid

This number decides your architecture. Clockify's API overview: There's a limit of 30 requests per hour per workspace if you're on the Free plan. Two other official pages repeat it — the API limitations page as Newly created workspaces on the Free plan are restricted to 30 API requests per hour, the export guide as 30 requests per hour for the free workspace.

Read per workspace literally — not per API key. A second key, or a colleague running their own copy, does not buy a second bucket. Paid workspaces sit on a different order of magnitude entirely: the same limitations page says Workspaces on any paid plan maintain the standard limit of 50 requests per second.

So budget. The script above spends one call on /v1/user, one per page of projects, one per page of entries — three requests for a freelancer's month at page-size=200. The naive design is what breaks: one request per day of the range, or one per project to resolve its name, and thirty days becomes thirty requests. Fetch wide, page large, cache the project map, and treat a 429 as a stop signal, not a retry cue.

Automation

A daily trigger, and the quotas that bite

Apps Script can run importHours on a schedule without you opening the file. Delete existing triggers for the handler first, or every deploy leaves another copy behind, each spending your Clockify quota.

Code.gs — install a once-a-day trigger

function installDailyTrigger() {
  ScriptApp.getProjectTriggers()
    .filter(function (t) { return t.getHandlerFunction() === 'importHours'; })
    .forEach(function (t) { ScriptApp.deleteTrigger(t); });

  ScriptApp.newTrigger('importHours')
    .timeBased()
    .atHour(6)
    .nearMinute(30)
    .everyDays(1)
    .inTimezone(SpreadsheetApp.getActive().getSpreadsheetTimeZone())
    .create();
}

nearMinute() is documented as the minute the trigger runs plus or minus 15 minutes, so the schedule is approximate. Import an overlapping window and rewrite the sheet each run rather than appending, so a repeated run cannot double your rows.

Google's quotas: triggers total runtime is 90 min/day on a consumer @gmail.com account, 6 hr/day on Google Workspace — a retry loop that sleeps can reach it. URL Fetch calls are 20,000/day consumer, 100,000/day Workspace, so Clockify's 30 per hour stops you long before Google does. Script runtime is 6 min per execution, and you may install at most 20 triggers per user per script.

On secrets: script properties are readable by anyone with edit access to the project. If the sheet is shared with people who should not have your key, use PropertiesService.getUserProperties(), which scopes it per user.

References

Sources

• Clockify API reference (v1) — auth, hosts, Last-Page, parameters, response samples.
• Clockify API overview — 30 requests/hour per Free workspace.
• Webhook and API limitations — 30/hour on Free, 50/second on paid plans.
• How to retrieve more than 50 results via API — default page size 50, max 5000 base / 1000 report.
• How to export data via API — reports/detailed body, pageSize: 1000, CSV/Excel as paid.
• Updates to the Clockify Free plan — rates, billable, export formats, report range.
• Apps Script quotas — URL Fetch, trigger and script runtime, triggers per user.