--- title: "Outreach send capacity for this shop" method: GET path: "/automations/outreach-capacity" tags: ["Automations"] --- # Outreach send capacity for this shop `GET /automations/outreach-capacity` ## Request - Base URL: `https://api.reacherapp.com/public/v1` - URL: `https://api.reacherapp.com/public/v1/automations/outreach-capacity` - Auth: API key in header `x-api-key` and API key in header `x-shop-id` Current outreach send-capacity for a single shop, so callers can pre-check before sending TC invites / DMs and schedule retries when capacity frees. Two independent limits govern outreach: * **Daily per-shop throttle** counted in **UTC** (resets at 00:00 UTC — see `daily_window_resets_at`). `daily_creators_used` counts actual sends only (skipped/`creator_not_found` invites do not count). The daily ceiling is plan/TikTok-dependent and is not returned as a single number; `daily_limit_throttled` flags when the shop is currently paused by it. * **TikTok's outreach quota**, enforced TikTok-side and read from TikTok's own quota endpoint — see `outreach_quota` for the consumption, ceiling and refresh instant. It counts connections shop-wide, so it includes outreach not sent through Reacher. Most shops are on a weekly `PERIOD` quota; some hold a `BONUS` grant that does not roll, so check `outreach_quota.quota_type` before calling it weekly. Null when the shop has no synced quota — null means unknown, never zero. `weekly_limit_throttled` flags when paused by the limit. The daily pool is **shared** between the automation engine and direct `POST /target-collabs` invites. Requires a single shop. ## Response `200` Successful Response - OutreachCapacityResponse: Current outreach send-capacity for a single shop. Two independent limits govern outreach (DM + TC) sends: 1. A **per-shop daily throttle** counted in UTC (resets at 00:00 UTC). `daily_creators_used` is the distinct (creator, automation) pairs the shop has reached today across all non-CRM, non-AI-Chatbot outreach automations. The *ceiling* is plan/TikTok-dependent and is not returned as a single number; `daily_limit_throttled` is true when any live automation is currently paused by the daily limit. 2. **TikTok's outreach quota**, enforced TikTok-side and read from TikTok's own quota endpoint — see `outreach_quota`, which carries the consumption, the ceiling, and the refresh instant for the current period. Most shops are on a weekly `PERIOD` quota; some hold a `BONUS` grant that does not roll, so check `outreach_quota.quota_type` before calling it weekly. `weekly_limit_throttled` is true when any live automation is currently paused by the limit. `outreach_quota` is null for a shop without the affiliate app authorized, or that has never synced — null means unknown, never zero. It is independent of `weekly_limit_throttled`: a throttled shop can still return null here, and its reset time is then unknown. The daily throttle pool is **shared** between the automation engine and direct `POST /target-collabs` invites — both draw from the same per-shop daily figure. - `shop_id` integer, required - `daily_creators_used` integer, required: Distinct (creator, automation) outreach sends counted for this shop in the current UTC day. Counts actual sends only — invites that were skipped (e.g. `creator_not_found`) do not count. - `daily_window_resets_at` string, required: ISO-8601 UTC timestamp of the next daily-window reset (next 00:00 UTC). - `concurrent_automations_running` integer, required: Outreach automations currently in a running/paused-but-live state. - `max_concurrent_automations` integer, required: Plan ceiling for concurrent automations. - `daily_limit_throttled` boolean, required: True when a live automation is currently paused by the daily outreach limit. - `weekly_limit_throttled` boolean, required: True when a live automation is currently paused by TikTok's weekly outreach limit. When true, daily capacity is moot until the weekly window resets. - `outreach_quota` OutreachQuota: TikTok's outreach quota for a shop's current period. Read from TikTok's own `/creator_outreach/quota` endpoint, not reconstructed from Reacher's send tables — the two cannot agree, because `used` counts connections shop-wide. It therefore includes outreach NOT sent through Reacher, and excludes contact with creators the shop is already connected to. Do not read it as "what Reacher sent". - `quota_type` string, required: `PERIOD` — the weekly allowance, refreshing at `resets_at`. `BONUS` — a standing grant that does NOT roll weekly; its `resets_at` can be far in the future. Do not present a BONUS quota as a weekly one. - `used` integer, required: Creators consumed from the quota this period, as TikTok reports it. Counts connections shop-wide. - `limit` integer, nullable, required: The ceiling. Null when the shop is unlimited — check `unlimited` rather than inferring from null. `0` is a real zero allowance. Always present (required) so an absent key can never be mistaken for an explicit null. - `remaining` integer, nullable, required: Creators the shop can still reach this period: `max(0, limit - used)`. Null when the shop is unlimited. - `unlimited` boolean, required: True when the shop has no ceiling for this quota. A tiered shop reads true here while each creator-level group is capped — see `tiered` and `tiers`. - `resets_at` string, nullable, required: ISO-8601 UTC timestamp when the quota refreshes, as declared by TikTok. For a BONUS quota this can be far future. Always present (required), nullable only if TikTok omitted it. - `gmv_tier` string, nullable: TikTok's granted GMV tier for this shop (e.g. "4", "5"). Same scale as `gmv_level` in the tier table. - `gmv_level_rule` unknown[], nullable: TikTok's live tier table for the shop's region. Each entry maps a GMV level to its weekly outreach quota ceiling and follower cap. - unknown - `tiered` boolean: True when the shop is on TikTok's tiered outreach quota: the weekly quota is split by creator level, and `tiers` carries each group's ceiling. TikTok then reports the shop-wide quota as `unlimited`, so read `tiers`, not `limit`. - `tiers` OutreachQuotaTier[], nullable: The tiered quota's creator-level groups, highest levels first. Null for a shop not on the tiered quota, or whose groups are not known yet. - `creator_levels` integer[], required: The creator levels sharing this group's quota, ascending. - `unlimited` boolean, required: True when the group has no ceiling; its limits and `remaining` are then null. - `standard_limit` integer, nullable, required: The standard pool's ceiling for the period. Null when unlimited or not reported. - `standard_used` integer, nullable, required: Creators reached from the standard pool this period. - `bonus_limit` integer, nullable, required: The bonus pool's ceiling. Null when unlimited or not reported. - `bonus_used` integer, nullable, required: Creators reached from the bonus pool. - `remaining` integer, nullable, required: Creators the group can still reach this period across both pools. Null when unlimited or unknown. ## Changes > 76 revisions in range; 1 not diffed. - **2026-10-19** `10090480c809`: 2 info - added the optional property `outreach_quota/anyOf[subschema #1: OutreachQuota]/tiered` to the response with the `200` status - added the optional property `outreach_quota/anyOf[subschema #1: OutreachQuota]/tiers` to the response with the `200` status - **2026-09-19** `291230805105`: 1 info - api operation id `automation_outreach_capacity_automations_outreach_capacity_get` removed and replaced with `automation_outreach_capacity` - **2026-09-04** `3ea20a9f734b`: 1 info - added the required property `outreach_quota/anyOf[subschema #1: OutreachQuota]/remaining` to the response with the `200` status - **2026-09-03** `578c830ce294`: 2 info - added the optional property `outreach_quota/anyOf[subschema #1: OutreachQuota]/gmv_level_rule` to the response with the `200` status - added the optional property `outreach_quota/anyOf[subschema #1: OutreachQuota]/gmv_tier` to the response with the `200` status - **2026-09-03** `30786bf76d4b`: 1 info - added the optional property `outreach_quota` to the response with the `200` status [Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/automations/outreach-capacity/get.md) --- [API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)