List worklogs

GEThttps://<your-url>/api/v2/worklogs

MCP id worklogs.indexAlso on this path: POST Log time

Returns booked hours, newest first by date.

Token scope: api:read:times
Without it: 403 insufficient-token-scope.
Permission: hours::read
Without it: 403 insufficient-permission.
Rate cost: 1 unit, read bucket. view=detail makes it 3. Adds: with_total=1 +2, each include +1, q +2.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: My hours for one week, with the task expanded

curl -G \
  'https://<your-url>/api/v2/worklogs' \
  --data-urlencode 'filter[user_id]=me' \
  --data-urlencode 'filter[date][gte]=2026-09-07' \
  --data-urlencode 'filter[date][lte]=2026-09-13' \
  --data-urlencode 'include=task' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/worklogs?filter[user_id]=me&filter[date][gte]=2026-09-07&filter[date][lte]=2026-09-13&include=task', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/worklogs?filter[user_id]=me&filter[date][gte]=2026-09-07&filter[date][lte]=2026-09-13&include=task');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/worklogs?filter[user_id]=me&filter[date][gte]=2026-09-07&filter[date][lte]=2026-09-13&include=task',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "date": "2026-09-10",
      "minutes": 150,
      "description": "Reviewed the invoice export and fixed the rounding",
      "project_id": 12,
      "project": null,
      "budget_id": 1,
      "budget": null,
      "task_id": 88,
      "task": null,
      "work_item_id": 41,
      "work_item": null
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1
    }
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}

11 more fields, listed under Response

A caller sees only their own entries unless they hold times::update_others or times::delete_others, and that narrowing is applied before any client filter, before pagination and before the count, so filter[user_id] widens nothing on its own. meta.page.total is null unless you ask for it with with_total=1, which adds 2 read units, because worklogs are usually an organisation's largest collection. q matches anywhere in description. project and work_item are on every row already, so naming either in ?include= is a 400; budget, task and user are the includable relations, and each additionally requires the read permission and token scope of its own prefix. There is no duration string and no is_in_review flag: format minutes yourself, and read review state as (exceeded_budget || billable_change_reason) && reviewed_by == null && invoice_id == null.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

43 parameters in 6 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

Cursor pagination only. Follow links.next.

per_pageinteger1 to 100

Rows per page. At most 25 when include names a to-many relation; a larger value is 400 invalid-query-parameter.

Default: 25

cursorstring

Opaque keyset cursor from a previous page's links.next. Never construct one by hand.

with_totalboolean

Whether meta.page.total is counted for this request.

Default: false

Filters

=: equals
[in]: any of a comma-separated list
[null]: true or false: whether it is empty
[gte][lte][lt]: at least, at most, less than

filter[budget_id]integer=[in][null]

Budget the hours are invoiced against.

A comma-separated list of at most 100 values.

filter[created_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lt]

Creation timestamp. Pair with sort=id for a stable full export.

filter[date]date (YYYY-MM-DD)=[gte][lte]

The calendar day the work happened. Combine gte and lte for a range.

filter[exceeded_budget]boolean

Whether the entry was booked knowing it exceeds its budget.

filter[invoice_id]integer=[in][null]

The invoice these hours were billed on. Use the null operator, filter[invoice_id][null]=true, to find uninvoiced hours.

A comma-separated list of at most 100 values.

filter[is_not_billable]boolean

Whether the hours are excluded from invoicing.

filter[is_overtime]boolean

Whether the hours count as overtime.

filter[project_id]integer=[in][null]

Project the hours are booked against.

A comma-separated list of at most 100 values.

filter[reviewed_by]integer=[in][null]

The reviewer who settled the entry. Use filter[reviewed_by][null]=true to find entries nobody has reviewed.

A comma-separated list of at most 100 values.

filter[sales_invoice_row_id]integer=[in][null]

The sales-invoice line these hours were billed on.

A comma-separated list of at most 100 values.

Search

qstring

Free-text search over description. At most one substring match per request: q together with a contains filter is 400 invalid-query-parameter.

Sorting

sortstring

Up to three keys, comma-separated, each optionally prefixed with - for descending.

Default: date

Key	Sorts by
`date`	The calendar day the work happened, newest first.
`id`	Id, ascending. An id never changes, so use this for a stable full export.
`updated_at`	Last-write timestamp; pair with the id tiebreaker for sync.

Prefix a key with - for descending.

Includes

includestring

Comma-separated names to inline, at most five.

Path	Adds	Cost
`budget`	The budget the hours are invoiced against.	+1
`task`	The task the hours are booked on, limited to the tasks you can see on the tasks collection.	+1
`user`	The employee the hours belong to.	+1

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

Response 200

Returns a page of TimeList rows.

dataarray of TimeList

The rows, each a TimeList.

meta.pagePageOptionalTotal

per_page, next_cursor, prev_cursor, total.

linksPageLinks

self, next, prev.

Each row is a TimeList: 23 fields.

Headers

ETag: A weak validator (W/"…") of the rendered page.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

datedate (YYYY-MM-DD)

The calendar day the work happened.

minutesinteger

Duration in minutes, between 1 and 1440.

descriptionstring≤ 255

What the employee worked on.

project_idinteger or null

Project the hours are booked against; null once that project is deleted.

projectRef or ProjectSummary or null

The project the hours are booked against, always expanded. Its customer_id is the customer to fetch with GET /api/v2/customers/{customer}; the customer itself is not nested.

budget_idinteger or nullServer-assigned

Budget the hours are invoiced against. Derived from the task, never accepted on a write; null when no task is set or the budget is deleted.

budgetRef or BudgetSummary or null

The budget the hours are invoiced against. Expanding it with ?include=budget additionally requires the budgets::read permission and a token scope covering the budgets prefix.

task_idinteger or null

Task the hours are booked on; null when the entry is not attached to one, or once that task is deleted.

taskRef or TaskSummary or null

The task the hours are booked on. Expanding it with ?include=task additionally requires the kanban::manage_self permission and a token scope covering the kanban prefix, and is limited to the tasks you can see on the tasks collection.

work_item_idinteger or null

Work item the hours are attached to; null when the entry is not attached to one, or once that work item is deleted.

work_itemRef or WorkItemSummary or null

The work item the hours are attached to, always expanded.

user_idinteger or nullServer-assigned

Employee the hours belong to. Assigned on create (from the authenticated user, or from on_behalf_of_user_id) and never writable afterwards; reassigning a worklog is a DELETE plus a POST.

userRef or UserSummary or null

The employee the hours belong to. Expanding it with ?include=user additionally requires the users::read permission and a token scope covering the users prefix.

is_not_billableboolean

Whether these hours are excluded from invoicing. Inferred from the task's is_billable flag (false without a task) on create and again whenever task_id is sent. Sending a value that differs from the inferred or current one requires billable_change_reason and puts the entry in a reviewer's queue; without it the write is a 422 on /billable_change_reason.

is_overtimeboolean

Whether the hours count as overtime. Sending it without the times::write_overtime permission leaves it false and adds an input_ignored warning rather than failing the write.

exceeded_budgetboolean

Whether the entry was booked knowing it exceeds its budget. Set on create only, and true whenever a reason is sent; setting it puts the entry in a reviewer's queue.

reasonstring or nullDetail onlyMultiline

Why the budget overrun was accepted. Sending it on create marks the entry as exceeding its budget. Once a reviewer has settled the entry it can no longer be changed: a PATCH that does answers 409 reason_reviewed.

billable_change_reasonstring or nullDetail onlyMultiline

Why the inferred billability was overridden. Required whenever is_not_billable is sent with a value that differs from the inferred or current one, on create and on PATCH alike; the override puts the entry in a reviewer's queue, reopening one a reviewer had already settled.

reviewed_byinteger or nullServer-assigned

The reviewer who settled the entry, once one has. Set by the review queue in plnnrly; this API exposes no way to write it.

invoice_idinteger or nullServer-assigned

The invoice these hours were billed on, once they have been. While it is set, the entry is locked: a write answers 409 with conflict.reason locked_by_invoice.