Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GetRetrievalInstruction

Gets a retrieval instruction. Also used to poll the terminal reporting of an asynchronous create or update.

Request Syntax


GET /retrievalinstructions/retrievalInstructionId?retrievalInstructionVersion=retrievalInstructionVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

retrievalInstructionId

The identifier of the retrieval instruction to get.

Length Constraints: Fixed length of 10.

Pattern: [a-z0-9]{10}

Required: Yes

retrievalInstructionVersion

The version to return: a version number, or DRAFT for the retrieval instruction's current reviewed content. When omitted, DRAFT is used. This default is permanent: omitting retrievalInstructionVersion will never resolve to a numbered version.

Length Constraints: Minimum length of 1. Maximum length of 9.

Pattern: (DRAFT|[1-9][0-9]{0,8})

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "createdAt": "string",
   "customerEncryptionKeyArn": "string",
   "description": "string",
   "instruction": { 
      "answerFormat": "string",
      "answerPolicy": "string",
      "persona": "string",
      "retrievalGuidance": "string"
   },
   "lastTransitionStatus": "string",
   "lastTransitionStatusReasons": [ 
      { 
         "code": "string",
         "fieldName": "string",
         "message": "string"
      }
   ],
   "latestVersion": "string",
   "name": "string",
   "retrievalInstructionArn": "string",
   "retrievalInstructionId": "string",
   "status": "string",
   "updatedAt": "string",
   "version": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

createdAt

When the retrieval instruction was created. On a numbered version, when that version was created.

Type: Timestamp

customerEncryptionKeyArn

The ARN of the customer managed KMS key protecting this content, when one was supplied at create.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: arn:aws(|-cn|-us-gov):kms:[a-zA-Z0-9-]*:[0-9]{12}:key/[a-zA-Z0-9-]{36}

description

A description of the retrieval instruction. On a numbered version, the description of that version.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

instruction

The reviewed content this instruction serves — what AgenticRetrieveStream resolves while status is ACTIVE. Absent until the first create review passes. Always present on a numbered version.

Type: RetrievalInstructionContent object

lastTransitionStatus

The outcome or in-progress state of the most recent create or update. CREATING or UPDATING means the operation is still running. Independent of status. Always has a value from the create 202 onward. On a numbered version this is always CREATE_SUCCESSFUL: a version is created once, from reviewed content, and is immutable.

Type: String

lastTransitionStatusReasons

Why the most recent create or update was rejected. One entry for each rejected field, or a single entry when the review itself failed. Each entry has a machine-readable code and a message, and names the field when it applies to one. The service includes this field only when lastTransitionStatus is CREATE_FAILED or UPDATE_FAILED. Never present on a numbered version.

Type: Array of RetrievalInstructionFailureReason objects

latestVersion

The largest version number that currently exists for this retrieval instruction, that is, the newest version you can retrieve. Present only on a DRAFT read, and only when at least one version exists. Because version numbers are never reused, deleting versions can leave gaps: this is the newest existing version, not a count and not the highest number ever created.

Type: String

Pattern: [1-9][0-9]{0,8}

name

The name of the retrieval instruction.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ([0-9a-zA-Z][_-]?){1,100}

retrievalInstructionArn

The ARN of the retrieval instruction.

Type: String

Pattern: arn:aws(-cn|-us-gov|-eusc|-iso(-[b-f])?)?:bedrock:[a-z0-9-]{1,20}:[0-9]{12}:retrieval-instruction/[a-z0-9]{10}

retrievalInstructionId

The identifier of the retrieval instruction.

Type: String

Length Constraints: Fixed length of 10.

Pattern: [a-z0-9]{10}

status

Specifies whether you can use the instruction. You can resolve only an ACTIVE instruction at retrieval time. Monotone: INACTIVE to ACTIVE once, never back. Numbered versions are always ACTIVE.

Type: String

Valid Values: ACTIVE | INACTIVE

updatedAt

When the retrieval instruction was last updated. Equal to createdAt on a numbered version, which is immutable.

Type: Timestamp

version

The version this response describes: a version number, or DRAFT.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 9.

Pattern: (DRAFT|[1-9][0-9]{0,8})

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

The request is denied because of missing access permissions.

HTTP Status Code: 403

InternalServerException

An internal server error occurred. Retry your request.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource Amazon Resource Name (ARN) was not found. Check the Amazon Resource Name (ARN) and try your request again.

HTTP Status Code: 404

ThrottlingException

The number of requests exceeds the limit. Resubmit your request later.

HTTP Status Code: 429

ValidationException

Input validation failed. Check your request parameters and retry the request.

fieldList: A list of objects containing fields that caused validation errors and their corresponding validation error messages.

HTTP Status Code: 400