# Retrieve task text evidence

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Retrieve task text evidence.

```text
POST https://api.moi.matrixorigin.cn/v5/semantic-models/runtime/search
```

## Before you call this API

Use injected service URLs, technical credentials, Workspace, and short-lived authorization only in the current task environment. Retain original authorization header values. An ordinary PAT cannot replace task identity or establish authorization. Examples use jq. See [Shared information](../../ai-studio/agents/message-connections/objects.md) for variables, objects, and states.

## Request body

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl -X POST "${MOI_ENDPOINT%/}/semantic-models/runtime/search" \
  -H "X-API-Key: $MOI_API_KEY" \
  -H "X-Workspace-ID: $MOI_WORKSPACE_ID" \
  -H "X-MOI-Runtime-Authorization: $MOI_RUNTIME_AUTHORIZATION" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg REQUEST_ID "$REQUEST_ID" --arg KNOWLEDGE_QUERY "$KNOWLEDGE_QUERY" '
{
  "request_id": $REQUEST_ID,
  "keywords": [
    $KNOWLEDGE_QUERY
  ],
  "max_hits": 3,
  "before": 2,
  "after": 1
}
')"
```

:::::
:::::{tab-item} Parameters

Text evidence and complete paragraphs remain in the raw artifacts objects. output may be a bounded view; a summary alone is not a complete read. source_page performs no semantic ranking. Continue with output.source_page.has_more/next_cursor and do not mix in ordinary fields.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | Yes | Unique ID for this operation, 1–256 bytes, without surrounding whitespace or an audit: prefix. Retain for replay of identical input. |
| `keywords` | string (array of strings) | Conditionally required | Supply valid keywords for ordinary retrieval; omit in source_page mode. |
| `max_hits` | integer | Conditionally required | Must be greater than 0 for ordinary retrieval. |
| `file_ids` | string (array of strings) | No | Restricted to sources allowed for the current task. |
| `volume_id` | string | No | Restricted to bound volume scope. |
| `max_rows` | integer | No | Nonnegative retrieval row limit. |
| `before` | integer | No | Nonnegative preceding-context expansion. |
| `after` | integer | No | Nonnegative following-context expansion. |
| `fulltext_only` | boolean | No | Uses full-text indexing without vector candidates. |
| `source_page` | object | No | Sequentially enumerates enabled paragraphs from the same source; mutually exclusive with ordinary retrieval fields. |
| `source_page.semantic_model_id` | integer | Conditionally required | Actual model ID returned by the source. |
| `source_page.file_id` | string | Conditionally required | File ID for the same source. |
| `source_page.cursor` | string | No | Original returned next_cursor value. |
| `source_page.page_size` | integer | No | 0/omission uses 20; maximum 100. Negatives rejected. |

:::::
::::::
:::::::

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "call_id": "request_example",
    "output": {
      "chunks": [],
      "row_count": 0
    }
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response description. |
| `data.call_id` | string | Corresponding original request_id. |
| `data.failed` | boolean | true indicates business failure; false may be omitted. |
| `data.output` | object | Current operation result. |
| `data.artifacts` | object (array of objects) | Original artifacts and evidence from the same task. |
| `data.metadata` | object | Operation metadata, returned when present. |
| `data.output.chunks` | array | Current text-result view; complete evidence is also stored in artifacts. |
| `data.output.row_count` | integer | Result row count or hit count for this operation. |

:::::
::::::
:::::::

## Error responses

Handle HTTP status, business results, and error fields separately. See [Errors and environments](../../ai-studio/agents/message-connections/objects.md#错误与环境). On source or version conflicts, read current state; do not automatically retry with a different identity, resource, or request ID.
