Search Casts

{
  "operationId": "search-casts",
  "method": "GET",
  "path": "/v2/farcaster/cast/search/",
  "summary": "Search for casts",
  "description": "Search for casts based on a query string, with optional AND filters",
  "tags": [
    "Cast"
  ],
  "parameters": [
    {
      "name": "",
      "in": "",
      "required": false,
      "description": ""
    },
    {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "Query string to search for casts. Supported operators:\n\n| Operator  | Description                                                                                              |\n| --------- | -------------------------------------------------------------------------------------------------------- |\n| `+`       | Acts as the AND operator. This is the default operator between terms and can usually be omitted.         |\n| `\\|`      | Acts as the OR operator.                                                                                 |\n| `*`       | When used at the end of a term, signifies a prefix query.                                                  |\n| `\"`       | Wraps several terms into a phrase (for example, `\"star wars\"`).                                          |\n| `(`, `)`  | Wrap a clause for precedence (for example, `star + (wars \\| trek)`).                                     |\n| `~n`      | When used after a term (for example, `satr~3`), sets `fuzziness`. When used after a phrase, sets `slop`. |\n| `-`       | Negates the term.                                                                                        |\n| `before:` | Search for casts before a specific date. (e.g. `before:2025-04-20` or `before:2025-04-20T23:59:59`)      |\n| `after:`  | Search for casts after a specific date. (e.g. `after:2025-04-20` or `after:2025-04-20T00:00:00`)         |",
      "schema": {
        "example": "star (wars | trek) \"space battle\" after:2024-05-04",
        "type": "string"
      }
    },
    {
      "name": "mode",
      "in": "query",
      "required": false,
      "description": "Choices are:\n- `literal` - Searches for the words in the query string (default)\n- `semantic` - Searches for the meaning of the query string\n- `hybrid` - Combines both literal and semantic results",
      "schema": {
        "enum": [
          "literal",
          "semantic",
          "hybrid"
        ],
        "example": "literal",
        "type": "string"
      }
    },
    {
      "name": "sort_type",
      "in": "query",
      "required": false,
      "description": "Choices are:\n- `desc_chron` - All casts sorted by time in a descending order (default)\n- `chron` - All casts sorted by time in ascending order\n- `algorithmic` - Casts sorted by engagement and time",
      "schema": {
        "enum": [
          "desc_chron",
          "chron",
          "algorithmic"
        ],
        "example": "desc_chron",
        "type": "string"
      }
    },
    {
      "name": "author_fid",
      "in": "query",
      "required": false,
      "description": "Fid of the user whose casts you want to search",
      "schema": {
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "name": "viewer_fid",
      "in": "query",
      "required": false,
      "description": "Providing this will return search results that respects this user's mutes and blocks and includes `viewer_context`.",
      "schema": {
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "name": "parent_url",
      "in": "query",
      "required": false,
      "description": "Parent URL of the casts you want to search",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "channel_id",
      "in": "query",
      "required": false,
      "description": "Channel ID of the casts you want to search",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Number of results to fetch",
      "schema": {
        "default": 25,
        "example": 25,
        "format": "int32",
        "maximum": 100,
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "Pagination cursor",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": null,
  "responses": {
    "200": {
      "description": "Success",
      "schema": {
        "$ref": "#/components/schemas/CastsSearchResponse"
      },
      "example": null
    },
    "400": {
      "description": "Bad Request",
      "schema": {
        "$ref": "#/components/schemas/ErrorRes"
      },
      "example": null
    }
  }
}