Skip to main content
POST
/
api
/
v2
/
ai
/
filter-wizard
Convert natural language to filters
curl --request POST \
  --url https://app.octolens.com/api/v2/ai/filter-wizard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "only negative tweets about pricing from the last 7 days"
}
'
{
  "filters": {
    "conditions": [
      {
        "field": "Keywords",
        "values": "42,43"
      }
    ]
  },
  "isAdvanced": true,
  "limit": 0,
  "includeAll": true,
  "view": 0,
  "explanation": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://octolens.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

Authorization
string
header
required

Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>.

Body

application/json

Convert a natural-language query into an Octolens filter object.

query
string
required

Natural-language description of what the user wants to see.

Required string length: 1 - 1000
Example:

"only negative tweets about pricing from the last 7 days"

Response

200 response

Filter object generated from a natural-language query. Client applies filters to the feed and shows explanation to the user.

filters
object
required

Generated filter object. null when the query is ambiguous. Use isAdvanced to determine whether it's the simple or advanced shape.

isAdvanced
boolean
required

If true, filters is an AdvancedFilters shape (AND/OR groups). Otherwise it's a SimpleFilters (flat AND list).

limit
integer
required

Requested page size — preserved from currentLimit unless the user asked to change it.

Required range: -9007199254740991 <= x <= 9007199254740991
includeAll
boolean
required

Whether to include low-relevance posts.

view
integer | null
required

View id the AI resolved the query against (if the user referenced a view by name). null otherwise.

Required range: -9007199254740991 <= x <= 9007199254740991
explanation
string
required

Plain-English summary of what the filter will match — shown in the UI.