--- title: "Research Agent" method: POST path: "/v1/research-agent" tags: ["Research Agent"] --- # Research Agent `POST /v1/research-agent` Execute a research query with AI-powered analysis and real-time data. Returns a streaming response via Server-Sent Events. ## Request body - ResearchAgentRequest — Request to execute a research query. - `chat_id` string, nullable — Provide a previous chat ID to continue a conversation. - `from_checkpoint_id` string, nullable — Resume or edit a conversation from a specific checkpoint. - `message` string, required — Your research question or request. - `model_name` 'base' | 'pro' — Available models for execution. - `persistence_mode` 'enabled' | 'disabled' — Controls whether conversation history is saved. - `research_effort` 'lite' | 'standard', required — Controls the depth and thoroughness of the research. - `structured_output_schema` object, nullable — JSON Schema for structured data extraction from the research results. - `tools_configs` object, nullable — Configuration for the search tool, including filters and ranking. - `search` SearchToolConfig — Configuration for the search tool. - `query_filters` QueryFilters — Filters applied to search queries to narrow results. - `content` ContentFilter — Composable content filter using logical operators. - `all_of` union[] — Match content satisfying all of these filters. - union - … - `any_of` union[] — Match content satisfying at least one of these filters. - union - … - `none_of` union[] — Exclude content matching any of these filters. - union - … - `entities` EntityFilter — Filter content by entity identifiers using logical operators. - `all_of` string[] — Match content mentioning all of these entity IDs. - `any_of` string[] — Match content mentioning any of these entity IDs. - `none_of` string[] — Exclude content mentioning any of these entity IDs. - `period` DateRange — Absolute time range for filtering content. - `end` string, date-time, nullable — End of the time range (ISO 8601 UTC, e.g. '2024-12-31T23:59:59Z'). - `start` string, date-time, nullable — Start of the time range (ISO 8601 UTC, e.g. '2024-01-01T00:00:00Z'). - `reporting_entities` string[] — Entity IDs of the company that authored or filed the document (for example, its own earnings-call transcripts and filings). Unlike `entities`, which matches documents that mention the company, this matches documents reported by the company. - `tags` string[] — Tags to filter on. - `ranking_parameters` RankingParameters — Parameters that influence how search results are ranked. - `freshness_boost` integer, nullable — Prioritize more recent content (1-10). - `source_boost` integer, nullable — Boost results from high-quality, authoritative sources (1-10). ## Response `200` Streaming SSE response with research results. - ResearchAgentResponse — A single streaming event from the Research Agent. - `chat_id` string, required — Identifier for this conversation. - `message` union, required — The streamed message event. - ThinkingMessage — The agent's intermediate reasoning while researching. - `content` string, required — The agent's reasoning text. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'THINKING' - ActionMessage — Notification that the agent is invoking a tool. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `tool_arguments` object, nullable — Arguments passed to the tool. - `tool_name` string, required — Name of the tool being called. - `type` 'ACTION' - AnswerMessage — A chunk of the agent's final answer text. - `content` string, required — Answer text content. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'ANSWER' - CompleteMessage — Signals that the agent has finished processing the request. - `checkpoint_id` string, nullable — Checkpoint for continuing this conversation. - `consumption` TokenTierConsumption[], required — Resource usage breakdown for this request. - `cached_tokens` integer — Number of tokens served from cache. - `input_tokens` integer, required — Number of input tokens consumed. - `output_tokens` integer, required — Number of output tokens generated. - `type` 'base' | 'pro', required — Model tier this consumption applies to. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'COMPLETE' - ErrorMessage — An unrecoverable error during processing. - `error` string, required — Error description. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'ERROR' - AuditMessage — Detailed trace data from tool executions. - `audit_traces` union[], required — Audit traces from tool executions. - union - SearchAuditV1 — Audit trace for a search operation. - `audit_type` 'SearchAuditV1' - `query` TraceQuery, required — A search query executed by the agent. - … - `results` union[], required — Search results grouped by source type. - … - `tool_id` string, required — Identifier of the tool that produced this trace. - MarkdownAuditV1 — Audit trace for generated markdown content. - `audit_type` 'MarkdownAuditV1' - `content` string, required — The generated markdown content. - `title` string, required — Title of the generated content. - `tool_id` string, required — Identifier of the tool that produced this trace. - StructuredReportAuditV1 — Audit trace for a structured data report. - `audit_type` 'StructuredReportAuditV1' - `structured_report` StructuredReport, required — A structured report with multiple sections. - … - `tool_id` string, required — Identifier of the tool that produced this trace. - SubAgentStartedAuditV1 — Audit trace emitted when a sub-agent begins its research task. - `agent_role` string, required — Role name of the sub-agent. - `audit_type` 'SubAgentStartedAuditV1' - `plan` PlanOutput — A structured research plan with ordered steps. - … - `plan_title` string, required — Title of the sub-agent's research plan. - `step_index` integer, required — Index of the plan step this sub-agent is executing. - `tool_id` string, required — Identifier of the tool that produced this trace. - SubAgentCompletedAuditV1 — Audit trace emitted when a sub-agent finishes its research task. - `audit_type` 'SubAgentCompletedAuditV1' - `consumption` TokenTierConsumption[] — Resource usage for this sub-agent's execution. - … - `success` boolean, required — Whether the sub-agent completed successfully. - `tool_id` string, required — Identifier of the tool that produced this trace. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'AUDIT' - GroundingMessage — Citations linking answer text spans to their sources. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `references` GroundingReference[], required — Source references for spans of the answer text. - `audit_id` string, required — Identifier linking this reference to its audit trace. - `end` integer, required — End character offset (exclusive) in the answer text. - `source` union — The referenced source document or web result. - ExternalResult — A result from an external web source. - `action` ExternalSourceAction, required — Metadata for an external web source. - … - `description` string, nullable — Brief summary. - `hd` string, required — Headline or title. - `id` string, required — Unique identifier for this result. - `text` string, required — Content text excerpt. - `ts` string, nullable — Publication timestamp. - `type` 'EXTERNAL' — Source type identifier. - BigdataDocument — A document from the Bigdata content platform. - `chunks` BigdataChunk[], nullable — Text chunks with matched content. - … - `content_type` string, nullable — Content type classification. - `document_scope` string, nullable — Scope or section of the document. - `document_type` string, nullable — Document type classification. - `hd` string, required — Document headline or title. - `id` string, required — Unique document identifier. - `language` string, required — Document language code. - `rp_provider_id` string, nullable — Provider identifier. - `source_rank` integer, required — Ranking weight of the source. - `src_key` string, required — Source key identifier. - `src_name` string, required — Source display name. - `ts` string, required — Publication timestamp. - `type` 'BIGDATA' — Source type identifier. - `url` string, nullable — URL of the original document. - `start` integer, required — Start character offset in the answer text. - `tool_name` string, required — Name of the tool that produced this reference. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'GROUNDING' - ToolErrorMessage — A recoverable error from a specific tool. - `error` string, required — Error description. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `tool_name` string, nullable — Name of the tool that encountered the error. - `type` 'TOOL_ERROR' - PlanningMessage — Updates to the agent's research plan. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `plan` PlanOutput, required — A structured research plan with ordered steps. - `steps` Step[] — Ordered list of research steps. - `description` string, required — What this step will investigate or produce. - `status` 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED' | 'SKIPPED' | 'FAILED' — Status of a research plan step. - `title` string, required — Short title summarizing the research objective. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'PLANNING' - LlmRetryMessage — Notification that the agent is retrying a failed operation. - `message` string, required — Human-readable retry status. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'LLM_RETRY' - StructuredOutputMessage — Structured data extracted from the research results. - `content` union, required — Extracted structured data matching the requested schema. - object - unknown[] - unknown - `json_schema` object, required — The JSON Schema used to produce this output. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'STRUCTURED_OUTPUT' ## Other responses - `422` — Validation Error --- [API](https://skmtc.dev/bigdata/apis/bigdata-structured-data-api.md) · [All operations](https://skmtc.dev/bigdata/apis/bigdata-structured-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bigdata/bigdata-structured-data-api/revisions/18082de268c4/schema)