# Search prediction records and candidates

Search sourced IELTS prediction records and their possible matching questions by record kind, source, exact id, date, month, subject, or keyword. Results preserve source attribution, distinguish dated exam reports from rolling rankings, and include practice targets only for candidates already in the question bank.

- Capability ID: `prediction.search_hits`
- Operation: `ielts_prediction_search_hits`
- Category: 备考内容
- Endpoint: `POST /api/v1/agent/capabilities/ielts_prediction_search_hits`
- Authentication: 无需认证
- Required scopes: prep:read
- Side effect: read
- Human documentation: https://ieltsbuddy.igopx.cn/developers/api/ielts_prediction_search_hits

## Request parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reportIds` | number[] | 否 | Optional exact prediction-record ids returned by an earlier search. |
| `kind` | string | 否 | Prediction record kind: dated exam reports or a rolling ranking snapshot. |
| `limit` | number | 否 | Result limit, 1-12. |
| `offset` | number | 否 | Pagination offset. |
| `query` | string | 否 | Optional recall, venue, source, or candidate-question keyword. |
| `source` | string | 否 | Optional prediction source slug, such as nine-score. |
| `subject` | string | 否 | Optional IELTS subject filter. |
| `testDate` | string | 否 | Optional exam date in YYYY-MM-DD. |
| `testMonth` | string | 否 | Optional exam month in YYYY-MM; use it instead of one call per day. |

## Request example

```bash
curl -X POST \
  'https://work.ieltsbuddy.igopx.cn/api/v1/agent/capabilities/ielts_prediction_search_hits' \
  -H 'Content-Type: application/json' \
  --data '{"reportIds":[],"kind":"exam_report","limit":6,"offset":0,"query":"","source":"","subject":"","testDate":"","testMonth":""}'
```

## Request schema

```json
{
  "type": "object",
  "properties": {
    "reportIds": {
      "default": [],
      "description": "Optional exact prediction-record ids returned by an earlier search.",
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "kind": {
      "default": "exam_report",
      "description": "Prediction record kind: dated exam reports or a rolling ranking snapshot.",
      "type": "string",
      "enum": [
        "exam_report",
        "rolling_ranking"
      ]
    },
    "limit": {
      "default": 6,
      "description": "Result limit, 1-12.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "query": {
      "default": "",
      "description": "Optional recall, venue, source, or candidate-question keyword.",
      "type": "string"
    },
    "source": {
      "default": "",
      "description": "Optional prediction source slug, such as nine-score.",
      "type": "string"
    },
    "subject": {
      "default": "",
      "description": "Optional IELTS subject filter.",
      "type": "string",
      "enum": [
        "",
        "listening",
        "reading",
        "speaking",
        "writing"
      ]
    },
    "testDate": {
      "default": "",
      "description": "Optional exam date in YYYY-MM-DD.",
      "type": "string",
      "pattern": "^(?:|\\d{4}-\\d{2}-\\d{2})$"
    },
    "testMonth": {
      "default": "",
      "description": "Optional exam month in YYYY-MM; use it instead of one call per day.",
      "type": "string",
      "pattern": "^(?:|\\d{4}-(?:0[1-9]|1[0-2]))$"
    }
  },
  "required": [
    "reportIds",
    "kind",
    "limit",
    "offset",
    "query",
    "source",
    "subject",
    "testDate",
    "testMonth"
  ],
  "additionalProperties": false
}
```

## Response envelope

```json
{
  "code": 0,
  "data": {},
  "message": "ok"
}
```

## Errors

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | `40001` | 请求参数不符合接口契约 |
| 404 | `40401` | 接口或目标资源不存在 |