List inbound agents
List your inbound agents — the applications that answer incoming calls.
List your inbound agents — the applications that answer incoming calls.
An inbound agent binds one of your agents to a destination that phone
numbers can be pointed at. Link a number to an application_sid and every
call to that number is answered by the bound agent; the link itself is made
by Graine when the number is provisioned, and GET /v2/phone-numbers
shows which numbers are already routed (is_inbound).
Only applications belonging to your organisation are returned; an application that is not tied to any organisation is not listed.
Your whole set of applications is read at once and then paged, with a ceiling of 500 applications per organisation. An organisation that has no numbers or carrier set up yet answers 404 rather than an empty page.
Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/inbound-agentsAuthorization
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
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 inbound applications.
dataRequiredData
This page of inbound applications.
paginationRequiredPagination
Where this page sits in the result set.
400
1000 — malformed or contradictory input (bad transfer target, bad timeout).
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
402
1400 — the organisation has insufficient credits for this request.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
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.
messageRequiredMessage
Human-readable single sentence.
404
1200 — no numbers or carrier have been set up for this organisation yet.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
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.
messageRequiredMessage
Human-readable single sentence.
503
1501 — a service this endpoint depends on is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
504
1502 — a service this endpoint depends on did not respond in time.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
A page of inbound applications.