---
title: "Query rows"
method: POST
path: "/webdbs/collections/{collection_id}/query"
tags: ["webdbs"]
---

# Query rows

`POST /webdbs/collections/{collection_id}/query`

Filters and sorts collection rows. Use `next_cursor` to load more results.

## Path parameters

- `collection_id` string, required — Collection ID.

## Request body

- WebdbsQueryRequest — Filters, sorts, and selects fields from collection rows.
  - `where` object — Filters rows by field values. Supports comparisons, lists, text matching, and boolean groups.
  - `order_by` object[] — Fields used to sort the results.
    - `field` string, required — Field used to sort rows.
    - `dir` 'asc' | 'desc' — Sort direction.
  - `select` string[] — Fields to include in each row. `_id` is always included.
  - `limit` integer — Maximum rows to return. Defaults to 25.
  - `cursor` string — Pagination cursor from a previous query.
  - `tags` string[] — Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.

## Response `200`

A page of matching rows

- WebdbsQueryResponse — A page of rows matching a query.
  - `data` WebdbsRow[], required — Rows in this page.
    - `_id` string, required — Row ID.
    - `_url` string, required — Final URL used to create the row.
    - `_status` 'pending' | 'active' | 'stale' | 'removed' | 'error' | 'cap_consumed', required — Current row status.
    - `_collection` string, required — Collection ID.
    - `_meta` object, required — System details for this row.
      - `first_seen_at` string, date-time, required — Time this row was first found.
      - `last_checked_at` string, date-time, required — Time this row was last checked.
      - `last_changed_at` string, date-time, nullable, required — Time the row values last changed.
      - `change_count` integer, required — Number of times the row changed.
      - `version` integer, required — Current row version.
      - `eligibility_score` number, nullable, required — Latest page eligibility score.
      - `extraction_confidence` number, nullable, required — Latest extraction confidence score.
      - `content_hash` string, nullable, required — Hash of the latest page content.
      - `credits_used` integer, required — Credits used to produce this row.
      - `capped_at` string, date-time, nullable, required — Time a credit limit stopped updates for this row.
      - `snapshot` object, nullable, required — Latest saved page snapshot.
        - `html_url` string — Temporary URL for the saved HTML.
        - `markdown_url` string — Temporary URL for the saved Markdown.
        - `captured_at` string, date-time, required — Time the page snapshot was saved.
      - `params` object, nullable, required — Values captured from the matching URL pattern.
        - `path` object, nullable, required — Values captured from named URL path segments.
        - `search` object, nullable, required — Values captured from URL query parameters.
      - `source` object, required — Source information for this row.
        - `target_id` string, required — Target that found this page.
        - `entry_urls` string[], required — Starting URLs that led to this page.
      - `fields` object, required — Extraction details for each field.
  - `has_more` boolean, required — Whether another page is available.
  - `next_cursor` string, nullable, required — Cursor for the next page, or null at the end.
  - `scan_limited` boolean — Whether the query stopped before scanning every possible match.
  - `key_metadata` object — API key usage for this request.
    - `credits_consumed` integer, required — The number of credits consumed by this request.
    - `credits_remaining` integer, required — The number of credits remaining for your organization after this request.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/context/apis/context-dev.md) · [All operations](https://skmtc.net/context/apis/context-dev/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/context/context-dev/versions/3c6a01ba967f/schema)