All jobs

Report Retainer Hours Used per Client From ClickUp Time Tracking

An agency's agent reads last month's ClickUp time entries, totals billable hours per client against each retainer, and flags clients running over or under.

Run this on RushOpens the console with this prompt ready to send. Connect ClickUp there first.

What the agent does

This is for a digital or marketing agency that sells monthly retainers (say 20 or 40 hours of design and content a month) and runs the work in ClickUp: one Folder or Space per client, a List per workstream, and the team's time logged on tasks with ClickUp's timer or as manual entries. At month end someone exports time, pivots it by client in a spreadsheet, and only then learns that one client used 31 of 20 hours while another used 6. The agent does that pass. It connects through ClickUp's remote MCP server, once, with POST /me/connections {"type": "mcp", "name": "clickup", "url": "https://mcp.clickup.com/mcp", "auth": {"mode": "oauth"}}, approved on ClickUp's own page by someone who can see every client's space. ClickUp's MCP server takes OAuth only, not API tokens.

The run starts with clickup_get_workspace_hierarchy to map Spaces, Folders and Lists to client names, and matches them to the retainer table in the prompt. It then calls clickup_get_time_entries for the month, filtering on dates and billable, and reads each entry's task so it can attribute the time to the client whose Folder holds that task's List. Entries on tasks outside any client Folder (internal meetings, sales pitches) go into a separate bucket instead of being forced onto a client.

For each client it totals billable hours, compares them with the allowance, and works out the share used. Where a client is over, it lists the five tasks with the most time and their assignees, using clickup_get_task for the task name and status, so the account lead sees whether the overrun was one big deliverable or many small requests. Where a client is under by more than a quarter, it says so too: an agency that bills a fixed retainer still wants to know a client is not getting the work they pay for.

It also checks the entries themselves. Time logged with no description, entries longer than ten hours, a running timer left on since before month end (clickup_get_current_time_entry shows only the signed-in user's own timer, so it reports the long entries it sees instead), and non-billable time on a client task each go on a short list for the operations lead to fix before invoices go out. It writes retainers.md and retainers.csv and changes nothing in ClickUp.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Report retainer hours for October 2026 from ClickUp. Map clients with clickup_get_workspace_hierarchy: each top-level Folder in the Space 'Clients' is one client. Retainers (hours per month): Harbor Dental 20, Juniper Outdoor 40, Lakeside Law Group 10, Maple Street Bakery 15. Read every time entry from 2026-10-01 to 2026-10-31 with clickup_get_time_entries and attribute it to the client whose Folder holds the entry's task; put entries outside the Clients space in 'Internal'. For each client give billable hours, allowance, percent used and the 5 tasks with the most time (name, status, assignee, hours). Flag clients over 100% or under 75%. List entries with no description, entries over 10 hours, and non-billable entries on client tasks. Write retainers.md and retainers.csv. Create, change and comment on nothing in ClickUp.",
  "connections": [
    "clickup"
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

Two files come back as artifacts on the session, each with a url that downloads it for an hour. retainers.md opens with one table, client by client, of allowance, hours used and percent, with the over and under rows marked, then a section per flagged client listing the tasks behind the number, then the clean-up list. retainers.csv has one row per client for the finance spreadsheet or invoicing tool. The session's result is a short summary of the same.

Before anyone invoices from it, the operations lead checks the clean-up list, because a forgotten twelve-hour entry moves a client from fine to over. They also check the Internal bucket: a client task filed in the wrong Folder lands there, and moving it in ClickUp then running the report again is quicker than editing the CSV. The transcript shows every MCP call the agent made, so a number in the table can be traced to the entries it was built from.

Run it on every first of the month

In the console, a Project automation with a schedule trigger (0 7 1 * * with the agency's timezone) can run a saved agent that names the ClickUp connection, with the retainer table in its instructions and the prompt asking for the previous month. When a retainer changes, editing the saved agent changes every later run.

A mid-month check catches overruns while they can still be managed: a second trigger on the 15th with a prompt for month to date. On plans without ClickUp's AI add-on the MCP server has a daily call budget per Workspace (1,000 calls in 24 hours on Business, per ClickUp's docs), so a workspace with many clients keeps these runs to a few a month.

The use case this job follows, with its automation and trigger: Produce a report or file, no repo.

Why run it on Rush?

A script against ClickUp's time-tracking API can total hours, but the useful part of this report is judgment: deciding that an entry on an untagged task belongs to Juniper because its List sits in Juniper's Folder, noticing that one client's overrun is a single redesign, and writing that in a sentence the account lead can forward. The agent does that from the same data, and the ClickUp sign-in stays in Rush's connection rather than a token in someone's spreadsheet macro.

Each run has its own computer and a record of every call and its cost, so the monthly report has a trail behind it when a client questions an invoice. The run needs no repository and no laptop left on over the weekend, and a second agency on the same org runs its own report with its own connection and saved agent.

Frequently asked questions

Does the agent need admin access in ClickUp?

The connection acts as the person who approved it on ClickUp's page, so the agent reaches the Spaces and time entries that person can. Approve it as someone who can view every client Space and everyone's time, or the totals will miss work.

Can it change time entries it thinks are wrong?

The prompt forbids it. ClickUp's MCP server does have tools that log and change time, so the instructions name what it may do: read, total and list. A person fixes entries in ClickUp and runs the report again.

Our retainers roll over unused hours. Can it handle that?

Put last month's carried hours next to each allowance in the prompt or the saved agent's instructions, and ask for the rolled-over balance as a column. The agent only knows the numbers it is given, so keep that table current.

What if a client has more than one Folder?

Name the Folders per client in the prompt, or tag client tasks consistently and tell the agent to group by tag. Anything it cannot place goes to Internal, where it is visible instead of hidden in another client's total.

More ClickUp jobs

More jobs like this: Produce a report or file, no repo

Keep reading