Time tracking

Activities, customers, phases and hours over a period, for programs and agents.

All paths are under https://your-workspace.albaticket.com/api/v1. An activity is one span of time: what was done, when it started and ended, and what it belongs to (a project, a customer, a ticket, labels). It is the same row the activities page and a ticket's Activities panel show, so time recorded here appears there at once, and POST /tickets/{key}/worklogs makes one too. Everything a program does here it does as the member, under the member's time and billing permissions: a member sees their own activities and, where they hold See all time, everyone's; rates and amounts appear only where they hold See billing.

Times and time zones

Answers give every moment in UTC with the offset (2026-09-24T07:00:00Z). A request may give a moment the same way, with any offset, and needs nothing more. A day (from, to: YYYY-MM-DD) or a local time without an offset (2026-09-24T09:00, or 11:00 for an end on the start's day) means nothing without a zone, so those requests take timezone, an IANA name such as Europe/Berlin, and are refused with 422 without it. Nothing is read from the member's account: the zone is the caller's to say, every time, and day buckets in a report are labelled in it.

Activities

`GET /activities`

The activities the member may see, newest first. All arguments are optional.

Argument
`from`, `to`	Days, inclusive, in `timezone`
`timezone`	Required with `from` or `to`
`project`	A project's key or name
`customer`	A customer's name
`ticket`	A ticket key
`tag`	One of its labels, matched without regard to case
`member`	`me`, or a person by name or id; others' activities need See all time
`running`	`true` for running activities only
`limit`, `offset`	Up to 100 a page, 20 by default

GET /activities?from=2026-09-21&to=2026-09-27&timezone=Europe/Berlin&project=WEB

{
  "activities": [
    {
      "id": "f2a9…",
      "description": "Reviewed the checkout flow",
      "started_at": "2026-09-24T07:00:00Z",
      "ended_at": "2026-09-24T09:30:00Z",
      "running": false,
      "time_spent_seconds": 9000,
      "time_spent": "2h 30m",
      "tags": ["review", "WEB-142"],
      "project": {"key": "WEB", "name": "Website"},
      "customer": {"id": "6b1d…", "name": "ACME"},
      "ticket": {"key": "WEB-142", "summary": "Checkout fails on Safari"},
      "note": {"format": "markdown", "text": "Two findings, both in the ticket."},
      "billable": true,
      "locked": false,
      "author": {"id": "5f0c…", "name": "Ada Lovelace"},
      "created_at": "2026-09-24T09:30:12.000211Z",
      "edited_at": null
    }
  ],
  "limit": 20,
  "offset": 0,
  "timezone": "Europe/Berlin"
}

`GET /activities/{id}`

One activity with its history: every change, oldest first, each with its kind (created, updated, stopped, locked, unlocked, deleted, imported), when, who, the agent it was made through (via) when one was, and the fields that changed.

`POST /activities`

Records an activity. Needs Log time on the project or customer, and Comment on the ticket's project for a ticket; an activity with neither project nor customer is the member's own. Answers 201 with the activity.

Field
`description`	What was done (required)
`start`	When it began: ISO 8601 with an offset, or a local time in `timezone`; now when left out
`end`	When it ended, as `start`, or `HH:MM` alone for the start's day (the next day when earlier)
`duration`	Instead of `end`: `1h 30m`, `45m`, `2d` (a day is 8 hours)
`timezone`	Needed with a local `start` or `end`
`tags`	Its labels, a list. A label that is the key of a ticket the member can see links the activity to the ticket, and sets its project
`project`	A project's key or name
`customer`	A customer's name; an activity for a customer with no project
`ticket`	A ticket key; the same as giving it as a label
`note`	A note, in Markdown
`billable`	Otherwise true when the activity has a customer, directly or through its project

Neither end nor duration makes a running activity, which POST /activities/{id}/stop ends; starting one stops the member's running activity, as the page does.

POST /activities
Content-Type: application/json

{"description": "Reviewed the checkout flow", "start": "2026-09-24T09:00", "end": "11:30",
 "timezone": "Europe/Berlin", "tags": ["review", "WEB-142"]}

`PATCH /activities/{id}`

Changes the fields given and leaves the rest; null (or "") for project, customer or ticket clears it. The member's own activities, or anyone's where they Manage billing for its customer or project. A locked activity is refused with 422 (locked).

`POST /activities/{id}/stop`

Ends a running activity now, or at end (with timezone when local). One that has ended is refused with 422 (not_running).

`DELETE /activities/{id}`

Deletes an activity, under the same rule as changing it. The deletion is soft: the activity leaves every list and total, its history records who deleted it, and the ticket's time spent comes down. Answers {"id": "…", "deleted": true}.

Customers and phases

`GET /organizations`

The organizations of the workspace, by name: the customers an activity, a project or a phase can belong to.

`GET /phases`

The phases (billing periods) the member may see, newest first, with customer narrowing them to one customer's. Each carries its dates, contract, customer, project and budget; rate and currency are given only where the member holds See billing for the phase's customer or project, and are null otherwise.

Hours

`GET /reports/hours`

Hours over a period, in total or grouped. The period is from and to (days in timezone), the current month when left out, or a phase (name or id), which fills the dates, the customer and the project as the reports page does. customer, project, ticket and member narrow it. group_by is total (the default), day, week (rows labelled by their Monday), project, customer, tag (by label, an activity counting fully towards each of its labels, Unlabelled for none), ticket or member.

GET /reports/hours?phase=September&timezone=Europe/Berlin&group_by=tag

{
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Berlin",
  "group_by": "tag",
  "phase": "September",
  "total_seconds": 37800,
  "hours": 10.5,
  "working_days": 22,
  "rate": "100",
  "currency": "EUR",
  "amount": "1050.00",
  "rows": [
    {"group": "dev", "seconds": 27000, "hours": 7.5, "amount": "750.00"},
    {"group": "review", "seconds": 10800, "hours": 3, "amount": "300.00"}
  ]
}

rate, currency and amount come with a phase whose rate the member may see (See billing); otherwise they are null and the rows carry no amount.

Permissions at a glance

Request	Needs
`GET /activities`, `GET /activities/{id}`	Own activities; others' with See all time on their project or customer, or on a ticket the member can see
`POST /activities`	Log time on the project or customer; Comment on the ticket's project for a ticket
`PATCH`, `DELETE /activities/{id}`, `POST …/stop`	The member's own; anyone's with Manage billing for its customer or project
`GET /organizations`	Any member
`GET /phases`	The phases the member may see; rates with See billing
`GET /reports/hours`	What `GET /activities` would show; amounts with See billing on the phase

A read-only token reads all of this and changes nothing.