GetMemoryTask
Queries the status, input, execute results, and error message of a memory extraction node. A successful node may not generate new memories. If a fault occurs, check the error field for the cause.
Operation description
Uses the taskId returned by AddMemories during asynchronous writes to query the progress and results of a memory extraction task.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:GetMemoryTask |
get |
*MemoryStore
|
None | None |
Request syntax
GET /workspaces/{workspaceId}/memorystores/{memoryStoreName}/memory-tasks/{taskId} HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| workspaceId |
string |
Yes |
The AgentCore workspace ID. |
ws-2f5f9c5a8d0e4c3b |
| memoryStoreName |
string |
Yes |
The MemoryStore name. |
customer-memory |
| taskId |
string |
Yes |
The task ID returned by AddMemories. |
task-2f5f9c5a8d0e4c3b |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
No parameters required.
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| requestId |
string |
The request ID. |
01A00000-0000-0000-0000-000000000001 |
| message |
string |
The response message. |
success |
| httpStatusCode |
integer |
The HTTP status code. |
200 |
| code |
string |
The business status code. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. |
|
| data |
object |
The task details. |
|
| taskId |
string |
The task ID. |
task-2f5f9c5a8d0e4c3b |
| triggerType |
string |
The task trigger type. Valid values:
Valid values:
|
AUTO |
| status |
string |
The extraction task status. Valid values:
|
SUCCEEDED |
| strategyConfig |
object |
The extraction strategy used for this task. |
|
| type |
string |
The memory extraction strategy type. Valid values:
Valid values:
|
auto |
| instruction |
string |
The custom extraction instructions used to restrict the content to be retained. If a conflict occurs with the memory base extraction instructions, this rule prevails. The auto type does not support non-empty instructions. |
Retain only long-term preferences explicitly expressed by the user |
| inputMessageCount |
integer |
The number of messages, events, or text entries input for this task. |
8 |
| inputTokenCount |
integer |
The number of tokens in the input content for this task. |
120 |
| memories |
array<object> |
Returned only when the task succeeds. An empty array is allowed. |
|
|
object |
|||
| memoryId |
string |
The long-term memory ID. |
mem-2f5f9c5a8d0e4c3b |
| changes |
array<object> |
The list of memory changes generated by the task, excluding memories that are not modified. |
|
|
object |
|||
| operation |
string |
The memory change type. Valid values:
Valid values:
|
ADD |
| memoryId |
string |
The unique identifier of the memory. |
mem-2f5f9c5a8d0e4c3b |
| error |
object |
The task error returned only when the status is FAILED or UNKNOWN. This does not indicate that the current query failed. |
|
| code |
string |
The task error code. |
UnknownError |
| message |
string |
The task error message. |
Memory extraction failed. |
| createdAt |
string |
The creation time in RFC 3339 format with time zone. |
2026-09-23T10:00:00Z |
| startedAt |
string |
The task start time in RFC 3339 format with time zone. This field is not returned if the task has not started. |
2026-09-23T10:00:00Z |
| finishedAt |
string |
The task completion time in RFC 3339 format with time zone. This field is not returned if the task has not finished. |
2026-09-23T10:00:01Z |
| input |
object |
The input content processed by this task. |
|
| type |
string |
The input content format. Valid values:
|
events |
| text |
string |
The raw text to be extracted for this task. |
The user likes hiking |
| messages |
array<object> |
The list of messages to be processed. |
|
|
object |
|||
| role |
string |
The message role. For example, user indicates the user, and assistant indicates the assistant. |
user |
| content |
string |
The body content of the memory. |
The user likes hiking |
| referenceTime |
string |
The reference time of this message in RFC 3339 format with time zone. If omitted, the request-level referenceTime is used. If both are omitted, the current request time is used. |
2023-05-08T13:56:00+08:00 |
| events |
array<object> |
The list of session events to be processed. |
|
|
array<object> |
|||
| eventId |
string |
The unique identifier of the event. |
evt-2f5f9c5a8d0e4c3b |
| timestamp |
integer |
The actual occurrence time of the event in Unix milliseconds, provided by the caller. |
1758614400000 |
| type |
string |
The event type. Valid values:
Valid values:
|
message |
| data |
object |
The event content. Select fields based on the event type. For message events, use role, content, and an optional callId. For compaction events, use eventIds and summary. For fork events, use parentScope and parentEventId. Do not mix fields from different event types. |
|
| role |
string |
The message role. Valid values: system, developer, user, assistant, and tool. The tool role also requires a callId. |
user |
| content |
array<object> |
The list of message content blocks. This field is required and can be an empty array. |
|
|
object |
|||
| type |
string |
The type of the message content block. Valid values: text, reasoning, tool_call, json, and opaque. |
text |
| text |
string |
The text of the text or reasoning content block. This field is required and can be an empty string. |
The user likes hiking |
| callId |
string |
The tool invocation ID. This field is required for tool_call content blocks and is used to associate subsequent tool messages. |
call-001 |
| name |
string |
The tool name. This field is required for the tool_call type. |
get_weather |
| arguments |
any |
The tool invocation parameters. This field is required for tool_call content blocks and supports JSON values. |
{"city":"Hangzhou"} |
| value |
any |
The data carried by the content block. This field is required for json and opaque content blocks and supports JSON values. |
{"preference":"hiking"} |
| format |
string |
The data format identifier for the opaque content block. A non-empty string is required. |
application/json |
| callId |
string |
The tool invocation ID. It is used to associate a tool invocation with its response message. |
call-001 |
| eventIds |
array |
The list of visible event IDs referenced by the summary. This field cannot be empty. |
|
|
string |
The event ID. |
evt-2f5f9c5a8d0e4c3b |
|
| summary |
string |
The summary content for the referenced events. This field cannot be empty. |
The user plans a weekend hiking trip |
| parentScope |
object |
The full association scope of the parent session. Each dimension must be consistent with those specified when the parent session was created. |
|
| userId |
string |
The business user ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes. |
user-001 |
| teamId |
string |
The business team ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes. |
team-001 |
| agentId |
string |
The agent ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes. |
agent-001 |
| sessionId |
string |
The session ID defined by the caller. If provided, it cannot be empty and can contain up to 128 UTF-8 bytes. |
session-001 |
| parentEventId |
string |
The event ID that serves as the cutoff position for historical references in the parent session. |
evt-2f5f9c5a8d0e4c3b |
| referenceTime |
string |
The reference time for interpreting relative times in the content, in RFC 3339 format with a time zone. If not provided, the time of the current request is used. |
2023-05-08T13:56:00+08:00 |
| metadata |
object |
The string key-value tags set by the caller. A maximum of 16 tags are supported. A key can contain up to 64 Unicode characters, and a value can contain up to 1024 Unicode characters. Empty strings are allowed. Nested objects or arrays are not supported. |
{"topic":"hiking"} |
|
string |
The metadata tag value set by the caller. |
hiking |
Examples
Success response
JSON format
{
"requestId": "01A00000-0000-0000-0000-000000000001",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": false,
"data": {
"taskId": "task-2f5f9c5a8d0e4c3b",
"triggerType": "AUTO",
"status": "SUCCEEDED",
"strategyConfig": {
"type": "auto",
"instruction": "仅保留用户明确表达的长期偏好。"
},
"inputMessageCount": 8,
"inputTokenCount": 120,
"memories": [
{
"memoryId": "mem-2f5f9c5a8d0e4c3b"
}
],
"changes": [
{
"operation": "ADD",
"memoryId": "mem-2f5f9c5a8d0e4c3b"
}
],
"error": {
"code": "UnknownError",
"message": "Memory extraction failed."
},
"createdAt": "2026-09-23T10:00:00Z",
"startedAt": "2026-09-23T10:00:00Z",
"finishedAt": "2026-09-23T10:00:01Z",
"input": {
"type": "events",
"text": "用户喜欢徒步旅行。",
"messages": [
{
"role": "user",
"content": "用户喜欢徒步旅行。",
"referenceTime": "2023-05-08T13:56:00+08:00"
}
],
"events": [
{
"eventId": "evt-2f5f9c5a8d0e4c3b",
"timestamp": 1758614400000,
"type": "message",
"data": {
"role": "user",
"content": [
{
"type": "text",
"text": "用户喜欢徒步旅行。",
"callId": "call-001",
"name": "get_weather",
"arguments": "{\"city\":\"杭州\"}",
"value": "{\"preference\":\"徒步旅行\"}",
"format": "application/json"
}
],
"callId": "call-001",
"eventIds": [
"evt-2f5f9c5a8d0e4c3b"
],
"summary": "用户计划周末徒步旅行。",
"parentScope": {
"userId": "user-001",
"teamId": "team-001",
"agentId": "agent-001",
"sessionId": "session-001"
},
"parentEventId": "evt-2f5f9c5a8d0e4c3b"
}
}
],
"referenceTime": "2023-05-08T13:56:00+08:00",
"metadata": {
"key": "hiking"
}
}
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter | The specified request parameter is invalid. | |
| 400 | UnsupportedOperation | The memory store does not support this operation. | |
| 500 | UnknownError | The request processing has failed due to some unknown error. | |
| 403 | Forbidden | You are not authorized to perform this operation. | |
| 404 | Resource.NotFound | The specified memory store does not exist. | |
| 429 | Throttling | Request was denied due to request throttling. | |
| 409 | Operation.Conflict | The memory store is not in a state that permits this operation. | |
| 409 | Resource.OperationConflict | The memory task cannot be queried in its current state. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.