Skip to content

Core concepts

Records and billing units

  • A record is one row of the database: a (domain, url, login, password) tuple.
  • A billing unit ("unit") is all records sharing the same (domain, login, password) for a matched domain, regardless of how many URLs they appear on.

Units are the atom of both billing and delivery:

  • Counts are always in units. A CSV file may contain more lines than its unit count, because a unit renders one line per URL.
  • A unit's URLs are never split across chunks — if a unit is in your chunk, all of its URLs are.

Snapshots

Matching runs against live data when your root search executes. From that moment, the matched set is frozen: later database changes do not affect your lineage's rows, per-row prices, or total cost. Prices and ordering are fixed at root creation.

Lineages, roots, and continuations

A search creates a root order. Each continuation creates a child order with its own CSV file. The root plus all its children form a lineage.

  • Any order id in a lineage works as a continue target — it resolves to the root automatically.
  • Every order in the lineage shares the root's expires_at (72 hours from root creation). Continuing does not extend it.
  • Orders are immutable accounting records and remain visible in GET /v1/orders forever, even after their files expire.
  • The lineage ends in 410 order_exhausted when remaining_rows hits 0, or 410 order_expired past the TTL.

Delivery order

Units are delivered in a fixed, deterministic order determined at root creation (a keyed hash of each unit — you don't need the details, only the guarantees):

  • The same query always yields the same ordering, so re-running a query returns the identical first-N units.
  • max_rows: N selects the first N units in that order — a deterministic quasi-random sample. It is not the cheapest or most expensive N.
  • Concatenated chunks of a lineage are gap-free and non-overlapping.

Source attribution

Each database source has its own per-row price. Every unit bills to its cheapest available source (ties break to the alphabetically smallest source name), and the CSV's source column reports that billing source — which can differ from where you first found the record.