> ## Documentation Index > Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt > Use this file to discover all available pages before exploring further. # List Messages > List messages for a task with offset-based pagination. For cursor-based pagination with infinite scroll support, use /messages/paginated. ## OpenAPI ````yaml https://agentex.dev-sgp.scale.com/openapi.json get /messages openapi: 3.1.0 info: title: Agentex API version: 0.1.0 servers: [] security: [] paths: /messages: get: tags: - Messages summary: List Messages description: >- List messages for a task with offset-based pagination. For cursor-based pagination with infinite scroll support, use /messages/paginated. operationId: list_messages_messages_get parameters: - name: limit in: query required: false schema: type: integer default: 50 title: Limit - name: page_number in: query required: false schema: type: integer default: 1 title: Page Number - name: order_by in: query required: false schema: anyOf: - type: string - type: 'null' title: Order By - name: order_direction in: query required: false schema: type: string default: desc title: Order Direction - name: filters in: query required: false schema: anyOf: - type: string - type: 'null' description: > JSON-encoded array of TaskMessageEntityFilter objects. Schema: { "$defs": { "DataContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "data", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `data`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The contents of the data message.", "title": "Data" } }, "title": "DataContentEntityOptional", "type": "object" }, "FileAttachmentEntity": { "description": "Represents a file attachment in messages.", "properties": { "file_id": { "description": "The unique ID of the attached file", "title": "File Id", "type": "string" }, "name": { "description": "The name of the file", "title": "Name", "type": "string" }, "size": { "description": "The size of the file in bytes", "title": "Size", "type": "integer" }, "type": { "description": "The MIME type or content type of the file", "title": "Type", "type": "string" } }, "required": [ "file_id", "name", "size", "type" ], "title": "FileAttachmentEntity", "type": "object" }, "MessageAuthor": { "enum": [ "user", "agent" ], "title": "MessageAuthor", "type": "string" }, "MessageStyle": { "enum": [ "static", "active" ], "title": "MessageStyle", "type": "string" }, "ReasoningContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "reasoning", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `reasoning`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "summary": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "A list of short reasoning summaries", "title": "Summary" }, "content": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "The reasoning content or chain-of-thought text", "title": "Content" } }, "title": "ReasoningContentEntityOptional", "type": "object" }, "TextContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "text", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `text`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "format": { "anyOf": [ { "$ref": "#/$defs/TextFormat" }, { "type": "null" } ], "default": null, "description": "The format of the message. This is used by the client to determine how to display the message." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The contents of the text message.", "title": "Content" }, "attachments": { "anyOf": [ { "items": { "$ref": "#/$defs/FileAttachmentEntity" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Optional list of file attachments with structured metadata.", "title": "Attachments" } }, "title": "TextContentEntityOptional", "type": "object" }, "TextFormat": { "enum": [ "markdown", "plain", "code" ], "title": "TextFormat", "type": "string" }, "ToolRequestContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "tool_request", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `tool_request`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The ID of the tool call that is being requested.", "title": "Tool Call Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The name of the tool that is being requested.", "title": "Name" }, "arguments": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The arguments to the tool.", "title": "Arguments" } }, "title": "ToolRequestContentEntityOptional", "type": "object" }, "ToolResponseContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "tool_response", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `tool_response`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The ID of the tool call that is being responded to.", "title": "Tool Call Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The name of the tool that is being responded to.", "title": "Name" }, "content": { "anyOf": [ {}, { "type": "null" } ], "default": null, "description": "The result of the tool.", "title": "Content" }, "is_error": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.", "title": "Is Error" } }, "title": "ToolResponseContentEntityOptional", "type": "object" } }, "description": "Filter model for TaskMessage - all fields optional for flexible filtering.\n\nThe `exclude` field determines whether this filter is inclusionary or exclusionary.\nWhen multiple filters are provided:\n- Inclusionary filters (exclude=False) are OR'd together\n- Exclusionary filters (exclude=True) are OR'd together and negated with $nor\n- The two groups are AND'd: (include1 OR include2) AND NOT (exclude1 OR exclude2)", "properties": { "content": { "anyOf": [ { "$ref": "#/$defs/ToolRequestContentEntityOptional" }, { "$ref": "#/$defs/DataContentEntityOptional" }, { "$ref": "#/$defs/TextContentEntityOptional" }, { "$ref": "#/$defs/ToolResponseContentEntityOptional" }, { "$ref": "#/$defs/ReasoningContentEntityOptional" }, { "type": "null" } ], "default": null, "description": "Filter by message content", "title": "Content" }, "streaming_status": { "anyOf": [ { "enum": [ "IN_PROGRESS", "DONE" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Filter by streaming status", "title": "Streaming Status" }, "exclude": { "default": false, "description": "If true, this filter excludes matching messages", "title": "Exclude", "type": "boolean" } }, "title": "TaskMessageEntityFilter", "type": "object" } Each filter can include: - `content`: Filter by message content (type, author, data fields) - `streaming_status`: Filter by status ("IN_PROGRESS" or "DONE") - `exclude`: If true, excludes matching messages (default: false) Multiple filters are combined: inclusionary filters (exclude=false) are OR'd together, exclusionary filters (exclude=true) are OR'd and negated, then both groups are AND'd. title: Filters description: > JSON-encoded array of TaskMessageEntityFilter objects. Schema: { "$defs": { "DataContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "data", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `data`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The contents of the data message.", "title": "Data" } }, "title": "DataContentEntityOptional", "type": "object" }, "FileAttachmentEntity": { "description": "Represents a file attachment in messages.", "properties": { "file_id": { "description": "The unique ID of the attached file", "title": "File Id", "type": "string" }, "name": { "description": "The name of the file", "title": "Name", "type": "string" }, "size": { "description": "The size of the file in bytes", "title": "Size", "type": "integer" }, "type": { "description": "The MIME type or content type of the file", "title": "Type", "type": "string" } }, "required": [ "file_id", "name", "size", "type" ], "title": "FileAttachmentEntity", "type": "object" }, "MessageAuthor": { "enum": [ "user", "agent" ], "title": "MessageAuthor", "type": "string" }, "MessageStyle": { "enum": [ "static", "active" ], "title": "MessageStyle", "type": "string" }, "ReasoningContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "reasoning", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `reasoning`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "summary": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "A list of short reasoning summaries", "title": "Summary" }, "content": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "The reasoning content or chain-of-thought text", "title": "Content" } }, "title": "ReasoningContentEntityOptional", "type": "object" }, "TextContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "text", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `text`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "format": { "anyOf": [ { "$ref": "#/$defs/TextFormat" }, { "type": "null" } ], "default": null, "description": "The format of the message. This is used by the client to determine how to display the message." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The contents of the text message.", "title": "Content" }, "attachments": { "anyOf": [ { "items": { "$ref": "#/$defs/FileAttachmentEntity" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Optional list of file attachments with structured metadata.", "title": "Attachments" } }, "title": "TextContentEntityOptional", "type": "object" }, "TextFormat": { "enum": [ "markdown", "plain", "code" ], "title": "TextFormat", "type": "string" }, "ToolRequestContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "tool_request", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `tool_request`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The ID of the tool call that is being requested.", "title": "Tool Call Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The name of the tool that is being requested.", "title": "Name" }, "arguments": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The arguments to the tool.", "title": "Arguments" } }, "title": "ToolRequestContentEntityOptional", "type": "object" }, "ToolResponseContentEntityOptional": { "properties": { "type": { "anyOf": [ { "const": "tool_response", "type": "string" }, { "type": "null" } ], "default": null, "description": "The type of the message, in this case `tool_response`.", "title": "Type" }, "author": { "anyOf": [ { "$ref": "#/$defs/MessageAuthor" }, { "type": "null" } ], "default": null, "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`." }, "style": { "anyOf": [ { "$ref": "#/$defs/MessageStyle" }, { "type": "null" } ], "default": null, "description": "The style of the message. This is used by the client to determine how to display the message." }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The ID of the tool call that is being responded to.", "title": "Tool Call Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The name of the tool that is being responded to.", "title": "Name" }, "content": { "anyOf": [ {}, { "type": "null" } ], "default": null, "description": "The result of the tool.", "title": "Content" }, "is_error": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.", "title": "Is Error" } }, "title": "ToolResponseContentEntityOptional", "type": "object" } }, "description": "Filter model for TaskMessage - all fields optional for flexible filtering.\n\nThe `exclude` field determines whether this filter is inclusionary or exclusionary.\nWhen multiple filters are provided:\n- Inclusionary filters (exclude=False) are OR'd together\n- Exclusionary filters (exclude=True) are OR'd together and negated with $nor\n- The two groups are AND'd: (include1 OR include2) AND NOT (exclude1 OR exclude2)", "properties": { "content": { "anyOf": [ { "$ref": "#/$defs/ToolRequestContentEntityOptional" }, { "$ref": "#/$defs/DataContentEntityOptional" }, { "$ref": "#/$defs/TextContentEntityOptional" }, { "$ref": "#/$defs/ToolResponseContentEntityOptional" }, { "$ref": "#/$defs/ReasoningContentEntityOptional" }, { "type": "null" } ], "default": null, "description": "Filter by message content", "title": "Content" }, "streaming_status": { "anyOf": [ { "enum": [ "IN_PROGRESS", "DONE" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Filter by streaming status", "title": "Streaming Status" }, "exclude": { "default": false, "description": "If true, this filter excludes matching messages", "title": "Exclude", "type": "boolean" } }, "title": "TaskMessageEntityFilter", "type": "object" } Each filter can include: - `content`: Filter by message content (type, author, data fields) - `streaming_status`: Filter by status ("IN_PROGRESS" or "DONE") - `exclude`: If true, excludes matching messages (default: false) Multiple filters are combined: inclusionary filters (exclude=false) are OR'd together, exclusionary filters (exclude=true) are OR'd and negated, then both groups are AND'd. examples: single_filter: summary: Filter by content type value: '{"content": {"type": "text"}}' multiple_types: summary: Filter multiple content types (OR) value: '[{"content": {"type": "text"}}, {"content": {"type": "data"}}]' with_exclusion: summary: Include data messages, exclude specific data types value: >- [{"content": {"type": "data"}}, {"content": {"data": {"type": "error_report"}}, "exclude": true}] nested_data: summary: Filter by nested data field value: '{"content": {"data": {"type": "report_status_update"}}}' - name: task_id in: query required: true schema: type: string description: The task ID title: Task Id description: The task ID responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/TaskMessage' title: Response List Messages Messages Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: TaskMessage: properties: id: anyOf: - type: string - type: 'null' title: Id description: The task message's unique id task_id: type: string title: Task Id description: ID of the task this message belongs to content: $ref: '#/components/schemas/TaskMessageContent' description: >- The content of the message. This content is not OpenAI compatible. These are messages that are meant to be displayed to the user. streaming_status: anyOf: - type: string enum: - IN_PROGRESS - DONE - type: 'null' title: >- In case of streaming, this indicates whether the message is still being streamed or has been completed created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: The timestamp when the message was created updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: The timestamp when the message was last updated type: object required: - task_id - content title: TaskMessage description: |- Represents a message in the agent system. This entity is used to store messages in MongoDB, with each message associated with a specific task. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TaskMessageContent: oneOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ReasoningContent' - $ref: '#/components/schemas/DataContent' - $ref: '#/components/schemas/ToolRequestContent' - $ref: '#/components/schemas/ToolResponseContent' title: TaskMessageContent discriminator: propertyName: type mapping: data: $ref: '#/components/schemas/DataContent' reasoning: $ref: '#/components/schemas/ReasoningContent' text: $ref: '#/components/schemas/TextContent' tool_request: $ref: '#/components/schemas/ToolRequestContent' tool_response: $ref: '#/components/schemas/ToolResponseContent' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError TextContent: properties: type: type: string const: text title: Type description: The type of the message, in this case `text`. default: text author: $ref: '#/components/schemas/MessageAuthor' description: >- The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. style: $ref: '#/components/schemas/MessageStyle' description: >- The style of the message. This is used by the client to determine how to display the message. default: static format: $ref: '#/components/schemas/TextFormat' description: >- The format of the message. This is used by the client to determine how to display the message. default: plain content: type: string title: Content description: The contents of the text message. attachments: anyOf: - items: $ref: '#/components/schemas/FileAttachment' type: array - type: 'null' title: Attachments description: Optional list of file attachments with structured metadata. type: object required: - author - content title: TextContent ReasoningContent: properties: type: type: string const: reasoning title: Type description: The type of the message, in this case `reasoning`. default: reasoning author: $ref: '#/components/schemas/MessageAuthor' description: >- The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. style: $ref: '#/components/schemas/MessageStyle' description: >- The style of the message. This is used by the client to determine how to display the message. default: static summary: items: type: string type: array title: Summary description: A list of short reasoning summaries content: anyOf: - items: type: string type: array - type: 'null' title: Content description: The reasoning content or chain-of-thought text type: object required: - author - summary title: ReasoningContent DataContent: properties: type: type: string const: data title: Type description: The type of the message, in this case `data`. default: data author: $ref: '#/components/schemas/MessageAuthor' description: >- The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. style: $ref: '#/components/schemas/MessageStyle' description: >- The style of the message. This is used by the client to determine how to display the message. default: static data: additionalProperties: true type: object title: Data description: The contents of the data message. type: object required: - author - data title: DataContent ToolRequestContent: properties: type: type: string const: tool_request title: Type description: The type of the message, in this case `tool_request`. default: tool_request author: $ref: '#/components/schemas/MessageAuthor' description: >- The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. style: $ref: '#/components/schemas/MessageStyle' description: >- The style of the message. This is used by the client to determine how to display the message. default: static tool_call_id: type: string title: Tool Call Id description: The ID of the tool call that is being requested. name: type: string title: Name description: The name of the tool that is being requested. arguments: additionalProperties: true type: object title: Arguments description: The arguments to the tool. type: object required: - author - tool_call_id - name - arguments title: ToolRequestContent ToolResponseContent: properties: type: type: string const: tool_response title: Type description: The type of the message, in this case `tool_response`. default: tool_response author: $ref: '#/components/schemas/MessageAuthor' description: >- The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. style: $ref: '#/components/schemas/MessageStyle' description: >- The style of the message. This is used by the client to determine how to display the message. default: static tool_call_id: type: string title: Tool Call Id description: The ID of the tool call that is being responded to. name: type: string title: Name description: The name of the tool that is being responded to. content: title: Content description: The result of the tool. is_error: anyOf: - type: boolean - type: 'null' title: Is Error description: >- Whether the tool call resulted in an error. `None` when the harness does not report a status. type: object required: - author - tool_call_id - name - content title: ToolResponseContent MessageAuthor: type: string enum: - user - agent title: MessageAuthor MessageStyle: type: string enum: - static - active title: MessageStyle TextFormat: type: string enum: - markdown - plain - code title: TextFormat FileAttachment: properties: file_id: type: string title: File Id description: The unique ID of the attached file name: type: string title: Name description: The name of the file size: type: integer title: Size description: The size of the file in bytes type: type: string title: Type description: The MIME type or content type of the file type: object required: - file_id - name - size - type title: FileAttachment description: Represents a file attachment in messages. ````