Get an agent's custom instructions
Learn more about how to retrieve an agent's custom instruction, administrator lock status, and last update time.
The Get an agent's custom instructions retrieves the effective custom instruction for the authenticated user and the specified agent. The response includes the instruction text, administrator lock status, and last update time.
HTTP method and endpoint
Use the following HTTP method and endpoint path to retrieve an agent's custom instruction.
GET https://{host}/ai/agentflow/api/v202605/{tenant_id}/agents/{agent_id}/custom-instructionsThe following table describes the endpoint path parameters.
| Parameter | Type | Required | Description |
|---|---|---|---|
tenant_id | String | Yes | Your tenant's unique identifier. |
agent_id | String | Yes | Identifier of the agent. Built-in agent IDs use uppercase letters, for example, MRA or EPRA2. IDs for custom agents use lowercase UUIDs. |
Request headers
The following request header must be included.
| Header | Value | Required |
|---|---|---|
Authorization | Bearer <access_token> | Yes |
Request body
This operation does not require a request body.
Example request
The following example shows a request to retrieve an agent's custom instruction.
GET https://{host}/ai/agentflow/api/v202605/{tenant_id}/agents/{agent_id}/custom-instructions
Authorization: Bearer <access_token>Response body
The following table describes the fields returned in the response body.
| Parameter | Type | Description |
|---|---|---|
agent_id | String | Agent identifier supplied in the request path. |
custom_instruction | String or null | Effective custom instruction text for the authenticated user. The value is null if the instruction was never set, and an empty string if it was cleared. |
locked | Boolean | Indicates whether a tenant administrator has disabled user-defined custom instructions for the agent.
|
updated_at | Datetime | Time of the last update, in ISO 8601 UTC format. |
Example response
The following example shows a successful response with the custom instruction, lock status, and update time.
{
"agent_id": "MRA",
"custom_instruction": "Always answer in French.",
"locked": false,
"updated_at": "2026-10-14T07:58:30.087566Z"
}Error codes and recommended actions
The following table lists the possible error responses returned by this API.
| HTTP status | Description | Recommended action |
|---|---|---|
401 Unauthorized | The access token is missing or invalid. | Provide a valid bearer access token and resend the request. |
403 Forbidden | The user lacks the required agent access, AI is not enabled for the tenant, or the agent is unavailable to the tenant or environment. | Verify that the token has agentflow:*, agentflow:agents.*, or agentflow:agents.EXECUTE permission for the tenant. Check tenant AI availability and agent access. |
500 Internal Server Error | An unexpected server error prevents the retrieval. | Retry the request. If the error persists, contact Reltio Support. |