---
title: "Find turns in a one-on-one AI conversation by keyword, date, media type, and/or Human/AI side."
method: POST
path: "/v1/search_chats"
tags: ["Conversation"]
---

# Find turns in a one-on-one AI conversation by keyword, date, media type, and/or Human/AI side.

`POST /v1/search_chats`

## Request

- Base URL: `https://partner.mindupload.app`
- URL: `https://partner.mindupload.app/v1/search_chats`
- Auth: API key in header `X-Partner-Key`

Search the signed-in user's one-on-one conversation with one AI consciousness. Combine an optional keyword with optional media types, unix date bounds, and optional `side` (`user` / `assistant` / `both`). Page with `cursor_value` + `cursor_id`. Use a hit id with `get_chat_around` to jump the dialogue UI.

## Request body

- object
  - `preferred_language` string, nullable: BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
  - `username` string, required: The end-user's username.
  - `password` string, required: The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
  - `clone_id` string, required: Owner AI consciousness id from `get_clones` (required for one-on-one find).
  - `keyword` string, nullable: Optional find query. Whole-word tokens across alphabetic and numeric scripts; character phrases for Chinese / Japanese / Korean; mixed language supported.
  - `content_media_types` string[], nullable: Optional list of media kinds to match: `image`, `video`, and/or `audio`.
  - `created_after` integer, nullable: Optional lower bound on message time as a UNIX timestamp in seconds.
  - `created_before` integer, nullable: Optional upper bound on message time as a UNIX timestamp in seconds.
  - `sort_order` -1 | 1, nullable: Turn send-time order: `-1` newest first (default), `1` oldest first.
  - `side` 'user' | 'assistant' | 'both', nullable: Optional 1v1 side filter: `user` (human), `assistant` (AI), or `both` (turns that include both sides).
  - `page_size` integer: Maximum Find hits for one page.
  - `cursor_value` number, nullable, required: Opaque pagination cursor value from the previous page (`next_cursor_value`).
  - `cursor_id` string, nullable, required: Opaque pagination cursor id from the previous page (`next_cursor_id`).

## Response `200`

Result envelope — check the success field.

- object
  - `success` boolean: Whether the call succeeded.
  - `error_message` string, nullable: Human-readable reason when success is false.
  - `error_code` string
  - `chats` object[], nullable: One-on-one turns returned by this operation.
  - `media_thumbnails` object, nullable: Mapping from an external media URL in a result to its preferred display URL (normally a retained thumbnail).
  - `media_fallbacks` object, nullable: Mapping from a provably expired signed image URL to a safe legacy display candidate.
  - `has_next` boolean, nullable: True when another page is available after this response.
  - `next_cursor_value` number, nullable: Pass as `cursor_value` on the next page request.
  - `next_cursor_id` string, nullable: Pass as `cursor_id` on the next page request.
  - `page_size` integer, nullable: Maximum records requested for one server-capped page.
  - `media_urls_expire_at` integer, nullable: UNIX timestamp after which cached result media links must be refreshed.

## Other responses

- `400`: Invalid request payload.
- `401`: Missing or invalid partner key.
- `403`: Partner is not authorized for this operation.
- `429`: Rate limit exceeded — retry later.
- `500`: Internal server error.

---

[API](https://skmtc.dev/mindupload/apis/mind-upload-partner-api.md) · [All operations](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/revisions/0371bdf78533?raw)