harvest-forecast-py

Python clients for the Harvest Forecast API and the Harvest API v2 — async and sync, with full coverage.

Features

• Full Forecast API coverage — All resources, mutations, aggregates, and meta endpoints from the Forecast API
• Harvest API v2 coverage — Clients, contacts, roles, tasks, users, projects, user/task assignments, time entries, invoices, estimates, create_time_entry, and whoami, with updated_since support on every list endpoint
• Async and sync clients — ForecastClient / HarvestClient for async/await code, SyncForecastClient / SyncHarvestClient for synchronous code
• Fully typed — Pydantic v2 models for all responses, type hints throughout, py.typed marker included
• Automatic retry — Configurable retry policy with exponential backoff and jitter for transient failures (429, 5xx, network errors)
• Pagination & windowing — Handles pagination and the 2520-day Forecast assignment date range limit internally; public paginate() methods yield raw payload dicts for pipelines that stage responses verbatim
• Structured exceptions — Typed exception hierarchy mapping HTTP status codes to specific errors
• Published on PyPI — Install with pip or uv, no build step required

Installation

# with pip
pip install harvest-forecast-py

# with uv
uv add harvest-forecast-py

Quick Start

Async

import asyncio
from datetime import date
from harvest_forecast import AssignmentFilter, ForecastClient

async def main() -> None:
    async with ForecastClient(
        access_token="your-personal-access-token",
        account_id="123456",
        user_agent="my-app (you@example.com)",
    ) as client:
        people = await client.list_people()
        for person in people:
            print(person.id, person.first_name, person.last_name)

        assignments = await client.list_assignments(
            AssignmentFilter(
                start_date=date(2026, 1, 1),
                end_date=date(2026, 1, 31),
            ),
        )

asyncio.run(main())

Sync

from datetime import date
from harvest_forecast import AssignmentFilter, SyncForecastClient

with SyncForecastClient(
    access_token="your-personal-access-token",
    account_id="123456",
    user_agent="my-app (you@example.com)",
) as client:
    people = client.list_people()
    for person in people:
        print(person.id, person.first_name, person.last_name)

    assignments = client.list_assignments(
        AssignmentFilter(
            start_date=date(2026, 1, 1),
            end_date=date(2026, 1, 31),
        ),
    )

Authentication

The Harvest Forecast API uses three pieces of credentials, all passed to the client constructor:

The client sends these as headers on every request:

• Authorization: Bearer {access_token}
• Forecast-Account-ID: {account_id}
• User-Agent: {user_agent}
• Accept: application/json

The library does not load configuration from environment variables or files — pass credentials as plain constructor arguments so callers control their own config.

API Overview

Resources

Meta Endpoints

Aggregates

All methods return materialized objects — internal pagination and date windowing are hidden from callers.

Harvest API v2

The same package ships clients for the Harvest API v2: HarvestClient (async) and SyncHarvestClient, authenticated with the same personal access token plus your Harvest account ID (sent as the Harvest-Account-Id header).

import asyncio
from datetime import datetime, UTC
from harvest_forecast import HarvestClient

async def main() -> None:
    async with HarvestClient(
        access_token="your-personal-access-token",
        account_id="123456",
        user_agent="my-app (you@example.com)",
    ) as client:
        # Incremental sync: everything changed in the last day
        entries = await client.list_time_entries(
            updated_since=datetime(2026, 7, 26, tzinfo=UTC),
        )
        invoices = await client.list_invoices(state="open")

asyncio.run(main())

Every list method accepts updated_since as a datetime (normalised to UTC, emitted as YYYY-MM-DDTHH:MM:SSZ) or as a pre-formatted string. Forecast-side list methods also expose paginate() / paginate_windowed() for raw payload access.

Breaking change in 0.3.0: the top-level HarvestClient export is now the async Harvest client (matching ForecastClient). In 0.2.x it aliased the sync client; use SyncHarvestClient for synchronous code.

Error Handling

The client maps HTTP status codes to a typed exception hierarchy before raising:

from harvest_forecast import (
    ForecastClient,
    ForecastAuthError,
    ForecastNotFoundError,
    ForecastRateLimitError,
    ForecastServerError,
    ForecastValidationError,
    ForecastHTTPError,
)

async with ForecastClient(...) as client:
    try:
        person = await client.get_person(999999)
    except ForecastAuthError:
        # 401 or 403 — invalid token or account ID
        ...
    except ForecastNotFoundError:
        # 404 — resource doesn't exist
        ...
    except ForecastRateLimitError as e:
        # 429 — rate limited (e.retry_after may have the Retry-After value)
        ...
    except ForecastServerError:
        # 5xx — server-side error
        ...
    except ForecastValidationError as e:
        # API returned an error body (e.g. missing required fields)
        print(e.response_body)
    except ForecastHTTPError as e:
        # Catch-all for other HTTP errors
        print(e.status_code, e.response_body)

All HTTP exceptions carry status_code: int, response_body: str, and url: str.

Retry

The client retries transient failures (429, 5xx, network errors) automatically using a configurable RetryPolicy:

from harvest_forecast import ForecastClient, RetryPolicy

# Default: 6 attempts, exponential backoff (1s → 60s), 2s jitter
async with ForecastClient(
    access_token="...",
    account_id="...",
    user_agent="...",
    retry=RetryPolicy(),
) as client:
    ...

# Disable retries
async with ForecastClient(
    ...,
    retry=RetryPolicy(max_attempts=1),
) as client:
    ...

Retry behavior:

• 429 / 5xx → retry with exponential backoff + jitter, honouring the Retry-After header
• Network errors (httpx.TransportError) → retry
• 4xx (non-429) → raise immediately, no retry
• Hard cap on attempts to prevent infinite loops in cron-triggered jobs

See the retry guide for details.

Documentation

Full documentation is available at https://AZX-PBC-OSS.github.io/harvest-forecast-py/.

License

MIT

Disclaimer

This project is unofficial and not affiliated with, endorsed by, or sponsored by Harvest Inc. or its subsidiaries. "Harvest" and "Forecast" are trademarks of their respective owners. This software is provided "as-is", without any warranty express or implied.

MIT — Copyright (c) 2025 AZX, PBC.