# Reach MCP — jobs

Every agent framework has a maximum runtime, and LinkedIn wants forty messages spread over a day, not fired in a minute. A **job** removes the choice between "send fast and risk the account" and "stay alive for hours calling one tool at a time": the agent deposits the batch in one call, gets a `job_id` back, and Reach does the rest.

What Reach does with a job:

- Spreads the items across the account's **activity window**: hours, days and timezone set per account (app → account → Quotas → Activity window, or `update_account_quotas` / `PATCH /api/linkedin-accounts/{id}/quotas` with `window_start`, `window_end`, `window_days`, `timezone`; default 09:00–18:00, Monday to Friday, timezone of the proxy country), overridable per job, with human-like, jittered gaps (never two items under 45 s apart).
- Caps every day at the **remaining daily quota** of the action, counting what other active jobs already hold; the overflow goes to the next working day. A batch that does not fit within 30 days is refused (`job_exceeds_capacity`) rather than silently truncated.
- Runs each item through the **same gate as a direct tool call** (billing, then quota, consumed one unit per item). A job can never do what a direct call could not.
- **Pauses by itself** when the quota is reached (`pause_reason: quota_reached`, `resume_at` set), when the account disconnects (`account_disconnected`, resumes when it reconnects) or when billing blocks writes; **resumes by itself** and re-plans the pending items. A manual pause (`pause_job`) is never auto-resumed.
- Retries a transient LinkedIn failure once, ten minutes later; a second failure marks the item `failed` and the job goes on.
- Reports every step through **webhooks** (below), so the agent does not poll.

## Actions (4)

| Action | Quota family | Required item fields | Optional | Does |
|---|---|---|---|---|
| `send_message` | messages | — | text, conversation_linkedin_id, recipient_linkedin_id, in_mail_premium | Send a LinkedIn message: text plus conversation_linkedin_id (reply) or recipient_linkedin_id (new). |
| `send_invitation` | invitations | linkedin_id_or_url | message | Send a connection request, with an optional note under 200 characters. |
| `visit_profile` | visits | linkedin_id_or_url | — | Visit a profile so the member gets a 'viewed your profile' notification. |
| `comment_post` | comments | post_url_or_urn, text | — | Comment on a post. |

Limits: 500 items per job. Item fields are the same as the direct tool's arguments (`send_message`, `send_invitation`, `visit_profile`, `comment_post`; `connect` is accepted as an alias).

## Where

- MCP tools: `create_job`, `get_job`, `list_jobs`, `cancel_job`, `pause_job`, `resume_job` (`create_job` accepts `idempotency_key`).
- REST: `POST https://app.reachmcp.com/api/jobs` (accepts `Idempotency-Key`), `GET https://app.reachmcp.com/api/jobs`, `GET https://app.reachmcp.com/api/jobs/{id}`, `POST …/jobs/{id}/cancel|pause|resume`, `GET https://app.reachmcp.com/api/jobs/actions`.
- App: **Jobs** page (progress, items, pause, resume, cancel); the account's default window is under its **Quotas** tab.

## Example (MCP)

```json
{"name": "create_job", "arguments": {
  "account_id": 12, "action": "send_message", "label": "Follow-ups week 40",
  "items": [
    {"conversation_linkedin_id": "2-MTU3…", "text": "Hi Anna, following up on the pricing question…"},
    {"recipient_linkedin_id": "ACoAAB…", "text": "Hi Marc, thanks for connecting…"}
  ],
  "window_start": "09:30", "window_end": "17:30", "days": ["mon", "tue", "wed", "thu"], "timezone": "Europe/Paris"
}}
```

The answer carries `status: scheduled`, `next_item_at`, `totals` and every item with its planned time. The agent's work is done; it can end its run.

## Job object

`id`, `account_id`, `action`, `label`, `status` (`scheduled` → `running` → `completed`; `paused`; `cancelled`), `pause_reason` (`quota_reached`, `account_disconnected`, `billing`, `manual`), `resume_at`, `window` (`start`, `end`, `days` 0 = Monday, `timezone`), `totals` (`total`, `done`, `failed`, `skipped`, `pending`), `next_item_at`, `source` (`mcp`, `rest`, `playbook`), `created_at`, `started_at`, `completed_at`, and on `get_job`/create `items[]` (`position`, `status` `pending|sending|done|failed|skipped|cancelled`, `scheduled_at`, `executed_at`, `attempt`, `payload`, `result`, `error`).

## Webhook events

| Event | When |
|---|---|
| `job.started` | A job executed its first item (data: job_id, action, label, total). |
| `job.progress` | A job item was executed: done or failed, with its result or error and the running totals. |
| `job.paused` | A job stopped by itself: the daily quota of its action was reached (resume_at tells when it resumes), the account disconnected (resumes when it is back), or billing blocks writes. |
| `job.completed` | Every item of a job has been executed (data: done, failed, skipped, total). |

Payloads always carry `job_id`, `action`, `label` and the running totals; `job.progress` adds the item (`item_id`, `position`, `status`, `result` or `error`); `job.paused` adds `reason` and `resume_at`. Subscribe an endpoint to `job.*` events on the Webhooks page or with `create_webhook_endpoint` — see [Webhooks](/docs/webhooks.md).

## Playbooks

The playbooks that write (`wake_cold_conversations`, `reactions_to_leads`, `viewers_to_leads`, `prospect_list`, `post_signals_to_leads`, `hiring_signals_to_leads`) tell the model to queue approved rows as one job when there are more than ten, so a "send these forty follow-ups" ends in one `create_job` call, not forty tool calls in a loop.
