---
title: "Retrieve source evidence directly without Ask"
method: POST
path: "/context"
---

# Retrieve source evidence directly without Ask

`POST /context`

## Request

- Base URL: `https://api.lochless.io/api/v1`
- URL: `https://api.lochless.io/api/v1/context`
- Auth: HTTP bearer

Scope: ask. Search uses the shared pipeline rate limit; other operations use the read tier. The key chooses the workspace and sees workspace connections only. No query_id is required. Omitted operation means search. Returns source text, provenance, versions, cost and coverage. Follow next_cursor with next_page_offset, and next_content_offset with source_version for full-source reads. Partial coverage is not evidence of absence. For calendar event browsing, set participant to an email or any.

Lochless workspaces: limit is results per page, default 50, up to 100. The response is results, total_results (every result the query has, across all pages), next_cursor (pass it back as cursor), tokens_scanned and request_id. Only the first page is charged; later pages of the same query are free. Filters (search and browse): from / to (ISO 8601, on the document's own timestamp; from inclusive, to exclusive; a YYYY-MM-DD date alone is that whole UTC day) and metadata ({key: value} exact match; a list value = any of). Only matching documents are read, scanned and billed. dry_run: true (search) returns documents_matched, documents_ready, tokens_to_scan and price_usd without scanning; free, rate-limited like a query. A dry run also returns read_limit_usd and complete (whether that limit reads every matching document).

Read limit (search): read_limit_usd caps what one call may cost, default 1. Over it, the best-matching documents are read first, and only what was read is billed. coverage is {mode, documents_read, documents_total, complete}. When complete is false the response has continue_cursor: send the same request with it to read the next best-matching documents, up to read_limit_usd again; no document is read twice. next_cursor pages stay free. 409 conflict: the documents changed since the first read; run the query again.

Read mode (search): mode is fast or complete. fast reads only the best-matching results (a lookup: one fact or answer), quicker and cheaper, and bills only what it read; it may miss matches. complete reads every matching document, up to read_limit_usd. Without mode the question decides. coverage.mode says which ran; a fast read has no continue_cursor (send mode: complete to read every match).

## Request body

- union
  - union
    - object
      - `operation` 'search', required
      - `query` string, required
      - `sources` string[], nullable: Optional sources for this subquery, within the user's task boundaries.
      - `limit` integer, required
      - `cursor` string
      - `page_offset` integer
      - `time_field` 'activity_at' | 'event_start' | 'source_updated_at' | 'indexed_at', required
      - `since` string, date-time
      - `until` string, date-time
      - `order` 'asc' | 'desc', required
      - `database_id` string
    - object
      - `operation` 'browse', required
      - `sources` string[], nullable: Optional sources for this subquery, within the user's task boundaries.
      - `limit` integer, required
      - `cursor` string
      - `page_offset` integer
      - `time_field` 'activity_at' | 'event_start' | 'source_updated_at' | 'indexed_at', required
      - `since` string, date-time
      - `until` string, date-time
      - `order` 'asc' | 'desc', required
      - `participant` string: For timed calendar events: me (default), any, or an attendee email.
      - `scan_after` object
        - `at` string, date-time, required
        - `id` string, required
    - object
      - `operation` 'read', required
      - `document_id` string, required
      - `connection_id` string, required
      - `source_version` string
      - `content_offset` integer, required
    - object
      - `operation` 'database', required
      - `database_id` string, required
      - `sources` string[], nullable: Optional sources for this subquery, within the user's task boundaries.
      - `limit` integer, required
      - `cursor` string
      - `page_offset` integer
      - `record_id` string
      - `revision` integer
      - `source_version` string
      - `content_offset` integer
  - object
    - `query` string, required
    - `sources` string[], nullable: Optional sources for this subquery, within the user's task boundaries.
    - `limit` integer, required
    - `cursor` string
    - `page_offset` integer
    - `time_field` 'activity_at' | 'event_start' | 'source_updated_at' | 'indexed_at', required
    - `since` string, date-time
    - `until` string, date-time
    - `order` 'asc' | 'desc', required
    - `database_id` string

## Response `200`

Source records, continuation fields, cost_usd, coverage and tokens_scanned (your text this call read, each piece once; 0 for browse and read). No composed answer.

## Other responses

- `400`: Invalid context request or forbidden identity fields
- `401`: Missing, invalid, revoked or expired API key
- `402`: spend_cap_reached (monthly spend cap reached) or add_credit (balance used up; top up in the console)
- `403`: Missing ask scope or unavailable source scope
- `409`: conflict: source, access or continuation changed; restart the read
- `422`: Unsupported filter, including calendar me for a workspace key
- `429`: Rate limit exceeded
- `502`: Context temporarily unavailable

---

[API](https://skmtc.dev/lochless/apis/synoptic-customer-api.md) · [All operations](https://skmtc.dev/lochless/apis/synoptic-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lochless/apis/synoptic-customer-api/revisions/e6dee3956611?raw)