Get an installed app
The app_installations.get operation: GET /api/v1/app_installations/{id} in the REST API and the app_installations_get tool in the MCP server.
GET
/api/v1/app_installations/{id}Returns one app installation of the organization: the app, the installer, scopes, limitTo and status.
At a glance
- REST:
GET /api/v1/app_installations/{id} - MCP tool:
app_installations_get - Operation ID:
app_installations.get - Scope: Organization
- Permission:
agents:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Authentication: API key with the
agents:readscope - Since: M10
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | ains_… ID |
Query parameters
This operation takes no query parameters.
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
id | ains_… ID | |
object | "app_installation" | |
orgId | org_… ID | |
app | object | |
app.id | ocl_… ID | |
app.name | string | |
app.publisher | string | |
app.logoUrl | string or null | |
app.verified | boolean | |
app.status | one of active, disabled | |
app.suspension | object or null | |
installedBy | usr_… ID | |
scopes | array of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) | |
limitTo | object | |
limitTo.entityIds | array of ent_… ID | |
limitTo.brandIds | array of brd_… ID | |
limits | object | |
limits.rps | integer or null | |
limits.mutationsPerDay | integer or null | |
limits.amountLimits | array of object | |
limits.amountLimits[].operationId | string | |
limits.amountLimits[].perCall | money or null | |
limits.amountLimits[].perDay | money or null | |
status | one of active, paused, revoked | |
pausedReason | one of manual, installer_lost_access, platform_suspended, app_disabled or null | |
pausedAt | string or null | |
revokedAt | string or null | |
createdAt | string | |
updatedAt | string |
Examples
An installation
HTTP
GET /api/v1/app_installations/ains_01m4ttwd3veh9apbewxheq5xhc
Authorization: Bearer or_test_…
Response (200):
JSON
{
"id": "ains_01m4ttwd3veh9apbewxheq5xhc",
"object": "app_installation",
"orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
"app": {
"id": "ocl_01m4ttwd3veh9apbewxheq5xha",
"name": "Ledgerly AI",
"publisher": "Ledgerly AI B.V.",
"logoUrl": null,
"verified": true,
"status": "active",
"suspension": null
},
"installedBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
"scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
"limitTo": {
"entityIds": ["ent_01m4ttwd3veh9apbewxheq5xh4"],
"brandIds": []
},
"limits": {
"rps": null,
"mutationsPerDay": null,
"amountLimits": []
},
"status": "active",
"pausedReason": null,
"pausedAt": null,
"revokedAt": null,
"createdAt": "2026-10-25T09:00:00.000Z",
"updatedAt": "2026-10-25T09:00:00.000Z"
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
resource_not_found | 404 | No installation with this ID exists in the organization. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
permission_denied | 403 | You can't see the organization's agents and apps. | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.