Core workflows

Search the Outtake index

Work with synchronous, asynchronous, and exact-match search

Outtake provides multiple search endpoints so you can balance speed, coverage, and precision. Start with the synchronous /search endpoint for instant results from the indexed corpus, or launch asynchronous jobs when you need to discover new content across supported platforms.

Search endpoints

  • POST /search — synchronous search across indexed content with lexical, semantic, or hybrid scoring.
  • POST /async-search — asynchronous discovery across platforms; returns a searchId to poll for status and match counts.
  • POST /async-search-exact — asynchronous exact-match detection on Twitter/X for phrases 25 characters or longer.
  • GET /async-search/{searchId} — retrieve status, match counts, and error details for asynchronous jobs.

Use the /search endpoint when you need an immediate response. You can tune precision and recall with searchType, lexical parser options, and similarity thresholds.

$curl --request POST "https://app.outtake.ai/api/v1/search" \
>  --header "Authorization: Bearer YOUR_API_KEY" \
>  --header "Content-Type: application/json" \
>  --data '{
>    "query": "generative AI scams",
>    "searchType": "hybrid",
>    "similarityThreshold": 0.35,
>    "pagination": { "pageIndex": 0, "pageSize": 25 },
>    "collectionIds": ["123e4567-e89b-12d3-a456-426614174000"]
>  }'

The response bundles the matched content, total hits, and sentiment distribution. Hybrid searches include both lexical and semantic scores so you can apply client-side ranking when needed.

Tuning results

  • Query parsing: websearch_to_tsquery (default) supports natural language phrases; switch to to_tsquery when you need fine-grained boolean operators like <-> or &.
  • Similarity threshold: Increase the similarityThreshold to tighten semantic matches. For hybrid queries, results pass when either the lexical match succeeds or the semantic score exceeds the threshold.
  • Collection filters: Pass collectionIds to scope the results to curated sets of content.

Asynchronous discovery

Async searches extend beyond the indexed corpus to new data sources. They queue background collection jobs and return immediately with a searchId.

$curl --request POST "https://app.outtake.ai/api/v1/async-search" \
>  --header "Authorization: Bearer YOUR_API_KEY" \
>  --header "Content-Type: application/json" \
>  --data '{"query": "brand impersonation deepfake"}'

Use POST /async-search-exact when you need literal phrase matches on Twitter/X. Exact search enforces a 25-character minimum to reduce noise.

Polling job status

Check job progress with GET /async-search/{searchId}. Poll until the status becomes completed or failed.

$curl --request GET "https://app.outtake.ai/api/v1/async-search/3b61305f-6a48-477a-8fd0-19a6a6d3f8fb" \
>  --header "Authorization: Bearer YOUR_API_KEY"

Responses include:

  • status: in_progress, completed, or failed.
  • result.matchCount and result.seenCount: counts of confirmed matches versus examined items.
  • error (when present): details for failed jobs.

Handling results downstream

Once an async job completes, use the returned counts to decide whether to:

  1. Launch targeted follow-up searches with /search using refined queries.
  2. Ingest results into a collection for ongoing monitoring.
  3. Trigger alerts or workflows when match thresholds are exceeded.

Best practices

  • Throttle polling: Start with a 15–30 second polling interval and back off as jobs approach completion.
  • Store search IDs: Persist searchId values so you can resume monitoring after restarts or handoffs.
  • Log parameters: Record the original query and filters alongside results to make investigations reproducible.
  • Favor hybrid search: Hybrid mode balances semantic recall with lexical precision, and is the recommended default for text queries in English and multilingual contexts.

Ready for a deeper dive? Review the search section in the API reference for field-level schemas and error codes.