All jobs

Total Each Consultant's Billable Meeting Hours by Client From Google Calendar

An invoicing app makes one agent per consultant that reads their Google Calendar for the month and drafts billable hours per client for the invoice.

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

What the agent does

This is for a company that makes invoicing and time-tracking software for independent consultants and small consultancies: coaches, fractional finance leads, designers who bill by the hour. Many of its users never start a timer; their billable time is already on their calendar as client calls and workshops. The company saves one agent as a template, POST /o/{org}/agents {"name": "Calendar hours", "harness": "claude", "instructions": "…", "connections": ["google-calendar"]}, after connecting a Google Calendar of its own, since a template names connections its creator has. When a user turns on "Fill from calendar", the backend makes that user's agent with {"template": "<template id>", "name": "hours-<your user id>"} and stores the id.

The user connects their calendar once: the backend calls POST /o/{org}/agents/{agent}/connections {"type": "app", "name": "google-calendar"} and opens the returned authorize_url in a popup, and the user approves on Google's own consent page. Rush asks Google for the Calendar scopes only, calendar.readonly and calendar.events, nothing for Gmail or Drive. The invoicing company registers no Google Cloud OAuth client and never sees a Google token.

At month end the app starts a run with the user's client list in input: each client's name, the email domains its people use, and any words that appear in that client's meeting titles. The agent calls the Calendar API's events.list on the user's primary calendar with timeMin and timeMax for the month, singleEvents=true so recurring meetings come back as separate occurrences, and orderBy=startTime, following nextPageToken to the end. It drops events with no dateTime (all-day events), events whose eventType is outOfOffice, focusTime or workingLocation, cancelled events, and meetings where the user's own entry in attendees (the one with self true) has a responseStatus of declined.

Each remaining event is matched to a client by its attendees' email domains first, then by its summary against the client's words. An event that matches two clients, or none but has outside attendees, goes on a list of questions instead of into a total. The agent adds up the minutes per client and returns line items the app can show for approval. It creates, edits and deletes no events: the template's instructions say so, even though the connection's calendar.events scope would allow it.

Start it with one API call

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

{
  "agent": "<agent id>",
  "input": "Total billable meeting time for October 2026 (America/New_York). Clients: Northwind Studio (domains northwind.example; title words 'Northwind', 'NWS'), Bluebird Health (domains bluebirdhealth.example), Carver & Lane (domains carverlane.example; title word 'C&L'). Call events.list on calendar primary with timeMin 2026-10-01T00:00:00-04:00, timeMax 2026-11-01T00:00:00-04:00, singleEvents true, orderBy startTime, following nextPageToken. Skip all-day events, cancelled events, eventType outOfOffice, focusTime and workingLocation, and events where my own attendee entry is declined. Match each event to a client by attendee email domain, then by title words. Return only JSON: clients (name, total_minutes, items with date, start, end, minutes, summary), questions (events that match two clients, or none but have attendees from outside my own domain, each with date, summary and attendee domains). Create, change and delete no events."
}
  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

The answer is that JSON, in the session's result and in the run.completed webhook's data.result, which carries the result in full up to 16 KiB; a busy month with many items may pass that, and then the backend reads the session for it. The app matches the webhook's execution_id to the user and month it started the run for and drafts one invoice line per client from total_minutes, with the items underneath so the consultant can strike out a call that was not billable.

The consultant checks questions first: a call with two clients' people on it, or a meeting with a new prospect's domain. They also check the rounding and rate rules the app applies after the run, which the agent does not know. Nothing reaches a client until the consultant approves the invoice in the app; the agent's totals are a draft built from the calendar, and a meeting that ran long or ended early shows its scheduled length, not the real one.

Run it on every month end, per consultant

On the first of each month the app's scheduler sends one POST /o/{org}/sessions per user with the feature on, each naming that user's agent, with their client list and the previous month in input, and a request_id that is a UUID v5 of the user's id and the month, so a retried job does not start a second run. Runs past the key's concurrent limit are created queued and start as slots free.

A user who adds a client mid-month can press "Refresh from calendar" to start the same run on demand. A user who revoked Rush's access in their Google account shows needs_reauth on GET /o/{org}/agents/{agent}/connections, and the app asks them to reconnect rather than drafting an empty invoice.

The use case this job follows, with its automation and trigger: Run an agent per customer task.

Why run it on Rush?

The calendar is where the hours already are, but turning it into an invoice is fuzzy matching: a recurring call renamed halfway through the month, a workshop booked from a client's personal address, an internal prep block with the client's name in it. A fixed set of rules misfiles those; an agent reading each event with the client list beside it puts them in the right place or asks. The company gets that without holding anyone's Google sign-in: each user's account belongs to their own agent, and an agent's run sees only that calendar.

Each run has its own computer, a transcript of every Calendar call and its cost, so a disputed line can be traced to the event behind it. GET /o/{org}/sessions?agent=<agent id> lists a user's runs with total_cost_usd, which tells the company what the feature costs per user. When a user cancels, DELETE /o/{org}/agents/{agent} removes their agent and disconnects their calendar.

Frequently asked questions

Does it read the contents of meeting notes or attachments?

It reads what events.list returns for each event, which includes the title, the description and the attendee list. The prompt matches on attendees and titles; if your users keep sensitive notes in descriptions, tell the template's instructions to ignore that field.

Can it bill for travel time or prep time?

Only if those are on the calendar as events it can match to a client. Many consultants block "Prep: Northwind" before a workshop, and the title words rule picks those up; the app can then apply a different rate to them.

What about meetings on calendars other than the primary one?

The prompt reads primary. A user who keeps client work on a second calendar can have the app pass that calendar's id instead, or the instructions can call calendarList.list first and read each calendar the user marks as work.

Will the agent change anything on the calendar?

No. The scope Rush asks for includes calendar.events, because the same app also serves agents that book meetings, so this template's instructions forbid creating, editing or deleting events, and each run's transcript shows every call it made.

More Google Calendar jobs

More jobs like this: Run an agent per customer task

Keep reading