Concepts

Why the vocabulary matters

Ray9 uses the same words in the dashboard, the API, the CLI, the MCP server, and these docs. A Flow is a Flow everywhere; a run is a run everywhere. If you learn the model once, every interface reads the same way.

Organization

The tenant. Members, roles, API keys, budgets, integrations, datasets, and usage all belong to an organization, and every access path checks it. If you work with more than one client or business unit, use more than one organization — there is no cross-organization leakage by design.

Template

A Ray9-maintained starter for a common job: a product page, a paginated directory, article extraction, change monitoring. You can search the catalog, see what a template outputs, what it needs from you, and how reliable it has been.

Forking a template copies it into your organization. Your copy does not silently track upstream changes; when the maintained template improves, Ray9 offers you an explicit, reviewable upgrade.

Flow

The thing you build and operate. A Flow holds the targets, the navigation steps, the extraction schema, the validation rules, any monitoring policy, execution preferences, and delivery configuration.

A Flow may scrape a page, crawl a set of them, monitor for change, or drive a browser — those are capabilities of one Flow, not four different products. (Calling an official connector is a capability the model reserves a place for; see Execution routes.)

A Flow always has an editable draft. It has published versions once you publish one.

Flow version

An immutable snapshot of a Flow's definition, created when you publish. Editing a published Flow creates a new draft; it never rewrites a version that already exists.

This is what makes results reproducible. Every run points at an exact version, so a record produced six months ago can be traced back to the precise definition that produced it. Schedules pin a version, and promoting a schedule to a newer one is a separate, deliberate, audited action.

A quick ad hoc run that was never saved as a Flow still carries an immutable definition snapshot — the same guarantee, without the Flow around it.

Run

One requested execution of a Flow version, or of an ad hoc snapshot. Runs come from the dashboard, a schedule, the API, the CLI, an MCP client, or a monitor — all of them create the same kind of run, with the same policy, credit, evidence, and output rules.

A run is durable: it survives process restarts, it can be cancelled, and it ends in exactly one outcome — complete, partial, policy_denied, budget_denied, action_required, failed, or cancelled. Note that failed is not a catch-all: a policy denial, a budget stop, and a usable partial result are each their own outcome.

Attempt

One try at one bounded piece of work inside a run, on one route. If the first route is blocked and an eligible fallback is allowed, the second try is a second attempt.

Attempts are mostly advanced evidence rather than something you manage. They are where the detail lives: which route ran, which provider, which browser profile, which egress class, the response metadata, the artifacts, the failure category, and the measured usage. Ray9 keeps every attempt, including the ones that failed — that is what makes an outcome explainable months later.

Schedule

A recurring trigger: a cron expression plus a named IANA timezone, attached to a pinned Flow version.

A schedule also carries an overlap policy (what to do if the previous run is still going), per-run caps, and an optional budget. Pausing a schedule stops future occurrences without deleting the configuration, and without cancelling a run that is already in flight. See Schedules.

Dataset

Where records live. A dataset has a versioned schema, a current table of records, and an append-only history of every observation ever made.

Datasets are queryable, filterable, and exportable as JSON or CSV, from the dashboard or the API. A Flow can create one automatically or write into a compatible existing one. See Datasets.

Record

One stable logical item — a product, a listing, an article — identified by a record key derived from fields you choose, from the canonical URL, or from an explicit expression.

The record is the identity. What changes underneath it is a series of observations: each one carrying its own values, the schema version that validated it, the run and Flow version that produced it, its validation status, and when it was observed. The current view shows you the latest; the history shows you all of them.

Monitoring policy

Optional Flow configuration that turns observations into change events.

It defines which fields to compare, what counts as meaningful (any change, a numeric threshold, an added or removed record), what to ignore as noise, and how many times a change must be confirmed before you hear about it. It compares normalized values — not raw HTML. See Monitoring.

Delivery

One attempt to get data out of Ray9 and into something else: a signed webhook, an export.

Deliveries are tracked as first-class objects, with their own event ID, attempt history, response codes, and retry state — so "did the record actually arrive?" is a question with an answer. See Webhooks.

Credits

Ray9's metered unit of work. A credit range is estimated before a run and a maximum is reserved; actual usage is accounted afterwards.

Heavier routes cost more: a direct HTTP fetch is cheaper than a stealth browser on a residential exit, because it costs Ray9 less to perform. Every grant, reservation, release, charge, refund, and adjustment is an entry in an append-only ledger, so your balance is always explainable rather than merely asserted. See Credits.