> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/time-tracking/harvest.md).
# Harvest
Pull time entries, invoices, expenses, and project data from Harvest into Google Sheets or BigQuery via Coupler.io.
Harvest is a time tracking and invoicing tool used by teams to log hours, manage projects, and bill clients. Connecting it to Coupler.io lets you pull your time entries, expenses, invoices, and project data into the tools you already use — automatically, on a schedule, with no code.
## Why connect Harvest to Coupler.io?
* **Automate your reporting** — stop manually exporting CSVs every week and let Coupler.io refresh your data on a schedule
* **Combine multiple entities** — use Join or Append transformations to merge Time entries with Projects, Clients, or Users into a single dataset
* **Send data anywhere** — destinations include Google Sheets, Excel, BigQuery, Looker Studio, and AI tools like ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw
* **Filter before you load** — reduce dataset size by filtering on date range, project ID, or update time so you only pull what you need
## Prerequisites
* An active Harvest account (any plan)
* Admin or Manager access in Harvest if you need to pull data across all users and projects (Members can only see their own data)
## Quick start
{% hint style="success" %}
Start with the **Time report** or **Time entries** entity — these are the most commonly used and give you the clearest picture of where hours are going across your team.
{% endhint %}
## How to connect
{% stepper %}
{% step %}
**Create a new data flow.** Log in to Coupler.io and click **Add data flow**. Search for **Harvest** and select it as your source.
{% endstep %}
{% step %}
**Authorize your Harvest account.** Click **Sign in with Harvest** and complete the OAuth flow. You'll be asked to choose which Harvest account to connect — select the correct one and approve access. Once authorized, you'll be returned to Coupler.io.
{% endstep %}
{% step %}
**Select an entity.** Choose the data you want to pull — for example, **Time entries**, **Report: Time report**, **Invoices**, or any of the other available entities. If your entity supports a date range (like the Time report or Expense report), set the **From** and **To** dates using the date picker.
{% endstep %}
{% step %}
**Choose a destination.** Select where you want your data to go — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination. Follow the prompts to authorize and configure your destination.
{% endstep %}
{% step %}
**Run your data flow.** Click **Run** to execute a manual import. Once it completes successfully, your data will appear in the destination you chose.
{% endstep %}
{% endstepper %}
## Available entities
| Entity | What it contains |
| ----------------------------- | ------------------------------------------------------ |
| Report: Time report | Aggregated time data by user, project, task, or client |
| Report: Expense report | Aggregated expense data by user, project, or client |
| Report: Uninvoiced report | Billable time and expenses not yet invoiced |
| Report: Project budget report | Budget vs. actual hours/costs per project |
| Time entries | Raw time log entries with hours, dates, and notes |
| Expenses | Individual expense records |
| Expense categories | Expense category definitions |
| Invoices | Invoice headers |
| Invoices with line items | Invoices including itemized line detail |
| Invoice item categories | Invoice line item category definitions |
| Estimates | Estimate headers |
| Estimates with line items | Estimates including itemized line detail |
| Estimate item categories | Estimate line item category definitions |
| Projects | Project list with budget and billing settings |
| Project task assignments | Tasks assigned to each project |
| Project user assignments | Users assigned to each project |
| Clients | Client list |
| Client contacts | Contacts associated with clients |
| Company | Your Harvest company/account settings |
| Users | Team member list and profile details |
| Roles | User role definitions |
| Tasks | Task list |
## Harvest data overview
Harvest exposes a wide range of data through Coupler.io — from raw time logs and expense records to rolled-up reports and billing documents. Here's a breakdown of what's available and how to use it.
## Entity types
| Type | Entities |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Reports (aggregated) | Time report, Expense report, Uninvoiced report, Project budget report |
| Time & expenses | Time entries, Expenses, Expense categories |
| Billing | Invoices, Invoices with line items, Invoice item categories, Estimates, Estimates with line items, Estimate item categories |
| Projects & tasks | Projects, Project task assignments, Project user assignments, Tasks |
| People & org | Users, Roles, Clients, Client contacts, Company |
## Metrics and dimensions
#### Time entries
| Field | Description |
| ------------------ | ------------------------------------------ |
| `hours` | Hours logged for the entry |
| `billable` | Whether the entry is billable (true/false) |
| `billable_rate` | Hourly rate applied if billable |
| `cost_rate` | Internal cost rate for the user |
| `spent_date` | Date the time was logged |
| `user.name` | Team member who logged the time |
| `project.name` | Project the time was logged against |
| `task.name` | Task associated with the entry |
| `client.name` | Client linked to the project |
| `is_running` | Whether the timer is currently active |
| `timer_started_at` | Timestamp when the timer started |
| `updated_at` | When the record was last modified |
| `notes` | Free-text notes on the entry |
#### Report: Time report
| Field | Description |
| ---------------------- | -------------------------------------------------- |
| `total_hours` | Total hours logged in the report period |
| `billable_hours` | Hours marked as billable |
| `currency` | Currency used for billing |
| `billable_amount` | Revenue value of billable hours |
| `spend_date` (From/To) | Date range for the report |
| Report type | Breakdown by client, project, task, or team member |
#### Report: Project budget report
| Field | Description |
| ------------------ | --------------------------------------- |
| `budget` | Total budget allocated to the project |
| `budget_spent` | Budget consumed to date |
| `budget_remaining` | Budget still available |
| `is_over_budget` | Whether the project has exceeded budget |
#### Report: Uninvoiced report
| Field | Description |
| --------------------- | ------------------------------- |
| `uninvoiced_hours` | Billable hours not yet invoiced |
| `uninvoiced_expenses` | Expenses not yet invoiced |
| `uninvoiced_amount` | Total uninvoiced revenue |
#### Invoices
| Field | Description |
| ------------- | ---------------------------------------- |
| `amount` | Total invoice amount |
| `due_amount` | Amount still outstanding |
| `state` | Invoice status (draft, open, paid, etc.) |
| `issue_date` | Date the invoice was issued |
| `due_date` | Payment due date |
| `client.name` | Client the invoice was sent to |
| `subject` | Invoice subject line |
#### Users
| Field | Description |
| ------------------------- | --------------------------------------------------------- |
| `first_name`, `last_name` | Team member name |
| `email` | Email address |
| `is_active` | Active status |
| `weekly_capacity` | Weekly capacity **in seconds** (divide by 3600 for hours) |
| `roles` | Assigned roles |
| `cost_rate` | Default cost rate |
| `default_hourly_rate` | Default billing rate |
## Common metric combinations
* **Utilization by team member** — Join Time entries + Users, group by `user.name`, compare `hours` to `weekly_capacity`
* **Client profitability** — Join Time entries + Invoices on `client.id`, compare `billable_amount` to `cost_rate × hours`
* **Budget burn rate** — Use the Project budget report and track `budget_spent` vs. `budget` week over week with Append
* **Unbilled work pipeline** — Use the Uninvoiced report filtered by date range to see revenue ready to invoice
## Use cases by role
{% tabs %}
{% tab title="Operations & project managers" %}
* Pull the **Project budget report** into Google Sheets or Looker Studio to monitor budget burn across all active projects in real time
* Use **Project user assignments** and **Time entries** with a Join transformation to see which team members are working on which projects and at what cost
* Track overdue deliverables by combining the **Uninvoiced report** with **Invoices** data
{% endtab %}
{% tab title="Finance teams" %}
* Export **Invoices with line items** to BigQuery for revenue recognition and cash flow tracking
* Use the **Uninvoiced report** to forecast incoming revenue before month-end close
* Combine **Expenses** with **Expense categories** to analyze spend by category across projects
* Send invoice aging summaries to ChatGPT or Gemini for narrative reporting
{% endtab %}
{% tab title="Team leads & HR" %}
* Export **Users** and **Time entries** to calculate actual utilization vs. capacity per team member
* Use **Roles** and **Project user assignments** together (Join) to see resource allocation by role
* Pull payroll-relevant data from **Users** and **Time entries** for headcount reporting — several teams use this for payroll inputs
{% endtab %}
{% endtabs %}
## Platform-specific notes
* The `weekly_capacity` field in the **Users** entity is returned in **seconds**, not hours. Divide by 3600 to convert to hours.
* The **"Changed after"** filter applies to the `updated_at` field — it is not the same as filtering by `spent_date`. If you want to pull entries for a specific time period, use the **Time report** entity with **From** and **To** date fields instead.
* The **Report: Time report** requires you to select a report type (by client, project, task, or team member) — this determines how rows are grouped.
* When filtering **Time entries**, **Invoices**, or **Expenses** by **Project ID**, you can only filter by one project at a time. Find the project ID in the Harvest URL when viewing a project.
* Advanced filters use lowercase field values — for example, use `true` not `TRUE` when filtering boolean fields like `is_active`.
## Harvest common issues
### Connection issues
My Harvest account isn't showing in the account list
If your Harvest account doesn't appear in the account dropdown, go to **Coupler.io → Connections**, find your Harvest connection, and click **Reconnect**. Then return to your data flow and try selecting the account again.
My data flow was working, then suddenly started failing
Harvest occasionally makes API changes without advance notice. If your data flow stops working after previously running successfully, check if the entity you're using (especially **Users**) has been affected. Try running the data flow manually and check the error message. If it references an API or parsing error, contact Coupler.io support — this type of issue is usually resolved on the platform side.
### Missing data
My import is missing rows I expect to see
The most common cause is a **"Changed after"** filter that's too restrictive. This filter applies to `updated_at` (when the record was last modified), not to `spent_date`. If you set it to a recent date, older records that haven't been touched won't be included — even if they fall within your reporting period.
For date-range filtering on actual work dates, use the **Time report** entity and set the **From** and **To** dates instead.
Data in Coupler.io doesn't match what I see in Harvest reports
Project and client IDs exported by Coupler.io should match Harvest's own IDs. If you see a mismatch, check whether you're comparing the same entity types — for example, Coupler.io's **Time entries** data differs from the aggregated **Time report**. Also confirm you're not filtering by project ID, which limits results to one project.
Project names are truncated or cut off
This can happen with long project names that include brackets or special characters at the start (e.g., `[C22-CLU001]`). This is a data parsing edge case — contact Coupler.io support with a screenshot of the affected row and the importer URL so the team can investigate.
### Permission errors
I can only see my own data, not data for all team members
Harvest restricts API access based on the role of the connected user. **Members** can only see their own time entries and projects. To pull data across all users, you need to connect using an **Administrator** or **Manager** account.
### Data discrepancies
The "Changed after" filter isn't working as expected
The **Changed after** field filters on `updated_at` — the timestamp when a record was last modified — not on the date work was performed. If you set this to January 1, records with an `updated_at` before that date won't appear, even if the work was done during your target period. Use the **Time report** with explicit **From** / **To** dates to filter by work date.
Advanced filters aren't working — all rows come through
Boolean values in advanced filters must be lowercase. Use `true` or `false` instead of `TRUE` or `FALSE`. This applies to fields like `is_active`, `billable`, and similar boolean columns.
Weekly capacity shows values in the millions (seconds instead of hours)
This is expected behavior. Harvest returns `weekly_capacity` in seconds via their API. Divide the value by 3600 to convert to hours. You can do this directly in the transformation step in Coupler.io or in your destination spreadsheet.
### Rate limits
My data flow times out or fails with large datasets
If you're pulling tens of thousands of rows (especially from **Time entries**), the Harvest API may time out before returning all data. To work around this:
* Add a date range filter using **From** and **To** to reduce the data volume
* Filter by **Project ID** to pull one project at a time
* Use the **Changed after** field to pull only recently modified records
* Split your data into multiple data flows, each covering a different date range or project, and use the **Append** transformation to combine them
{% hint style="warning" %}
If your dataset exceeds your plan's row limit, Coupler.io will disable automatic refresh. Use date filters to stay within limits.
{% endhint %}
## Harvest FAQ
What's the difference between "Time entries" and "Report: Time report"?
**Time entries** returns one row per individual log entry — with fields like hours, notes, user, project, and task. It's raw data, best for payroll inputs or custom calculations.
**Report: Time report** returns aggregated rows grouped by a dimension you choose (client, project, task, or team member). It's faster to work with for dashboards and summaries, and supports a date range filter via From and To fields.
How do I filter Time entries by the date work was done (not when it was last edited)?
The **"Changed after"** field in Time entries filters on `updated_at` — the last time the record was modified. To filter by the actual work date (`spent_date`), use the **Report: Time report** entity instead, which has explicit **From** and **To** date fields tied to when the work was performed.
Can I filter by team member, billable status, or other fields?
Yes — use **Advanced filters** in the data flow settings. For boolean fields like `billable` or `is_active`, make sure to enter values in lowercase (`true` or `false`). For filtering by team member, you can filter on `user.name` in Time entries, or choose "team member" as the report type in the Time report.
Why is my weekly_capacity showing a huge number instead of hours?
Harvest returns `weekly_capacity` in **seconds** via their API — this is documented behavior, not a Coupler.io bug. Divide the value by 3600 to get hours. You can add a calculated column in your destination spreadsheet or use a transformation step in Coupler.io to do this automatically.
How do I find a Project ID to use as a filter?
Open Harvest and navigate to the project. Look at the URL in your browser — the project ID is the number after the last slash. For example, in `https://couplerio3.harvestapp.com/projects/29290029`, the ID is `29290029`. Paste this into the **Project ID** field in Coupler.io. Note that you can only filter by one project at a time.
Can I combine data from multiple Harvest accounts?
Yes. Create a separate data flow for each account and use the **Append** transformation to combine them into one destination. This is useful for agencies or holding companies managing multiple Harvest accounts.
My data flow hits the row limit. How do I reduce my dataset size?
The most effective approaches are:
* Set a **From** and **To** date on Time report entities to limit the reporting window
* Use the **"Changed after"** filter on Time entries to pull only recently modified records
* Filter by **Project ID** to pull one project at a time
* Split your data across multiple data flows and use **Append** to combine them
{% hint style="info" %}
See [Common Issues](#harvest-common-issues) for more on rate limits and timeouts.
{% endhint %}
Can I send Harvest data to an AI tool like ChatGPT or Claude?
Yes. Coupler.io supports AI destinations including **ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw**. This is useful for generating narrative summaries of time reports, flagging over-budget projects, or creating client-ready writeups from raw billing data.
I only see my own data — why can't I see data for other team members?
Harvest API access is role-dependent. If you connected using a **Member**-level account, you'll only see your own records. To pull team-wide data, reconnect using an **Administrator** or **Manager** Harvest account.
{% hint style="info" %}
See [Common Issues → Permission errors](#harvest-common-issues) for steps to reconnect.
{% endhint %}
Can I join Harvest data with data from another source?
Yes. Coupler.io's **Join** transformation lets you combine Harvest data with other sources in the same data flow. For example, you could join Harvest time entries with a project list from a project management tool, or combine Harvest invoices with payment data from your accounting software.
{% hint style="info" %}
For ideas on which entities to combine, see [Data Overview → Common metric combinations](#harvest-data-overview).
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/sources/category/time-tracking/harvest.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.