List campaigns
List this organization's campaigns, newest first.
List this organization's campaigns, newest first.
total is an honest count of the matching campaigns, not a page-size
echo, so total_pages and has_more can be trusted.
The counters on each row (completed_calls, failed_calls and the
rest) are the campaign's stored roll-ups: cheap, and accurate to within the
last webhook. For the live, contact-level numbers a progress bar should use
— the ones that always sum to the total — read
GET /v2/campaigns/{campaign_id}/stats.
Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/campaignsAuthorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Query Parameters
statusStatus
Filter by state: created | active | paused | completed | cancelled | expired | archived.
organization_idOrganization Id
Must match the organisation the API key belongs to.
pagePage
1-indexed page number (max 10000 — narrow the window instead)
1Minimum: 1Maximum: 10000page_sizePage Size
Items per page (max 100)
20Minimum: 1Maximum: 100Response Body
200
A page of campaigns, newest first.
dataRequiredData
The campaigns on this page, newest first.
paginationRequiredPagination
page, page_size, total, total_pages, has_more.
400
1000 — malformed or contradictory input: an unknown timezone, a working-hours window that is not 24-hour HH:MM, an end_time at or before start_time, or an empty patch body. 1002 — a required parameter is missing.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
404
1200 — no such campaign, or no such agent, in this organisation. A campaign belonging to another organisation answers 404, never 403, so ids cannot be probed.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — per-organisation rate limit exceeded. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — the agent service is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
504
1502 — the agent service did not respond in time.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
A page of campaigns, newest first.