Skip to content
Rival Docs

How Runs Work

When you call a tool on Rival, the platform handles everything between your request arriving and the response coming back: checking the API key, routing to the right version, running your handler, recording the result, and deducting the run cost. You write the tool; Rival runs it.

The stateless model

Tools on Rival are stateless. Every run is fully independent - no shared memory between calls, no cached state carried over, no leftover files. Each run starts clean with only the event you send in and the environment variables attached to the tool.

This is a deliberate design choice. Stateless runs are predictable: a tool called once behaves identically to the same tool called a thousand times in parallel, because each run is isolated from the others. Scaling, routing, and capacity are all managed by the platform - you don’t configure servers or set concurrency limits.

If your tool needs to remember something between runs, that state has to live somewhere persistent. See Storage for your options.

The lifecycle of a run

A single run on Rival goes through four stages: auth → route → run → respond.

1. Request arrives

A caller sends a POST request to the invocation endpoint with their API key in the Authorization header, the tool ID and version in the URL path, and the event payload in the request body. See APIs for the request format.

2. Validation (auth)

Before your code runs, the platform checks four things:

  • API key - is it valid and tied to an organization with access to this tool?
  • Wallet balance - does the organization have enough credits to cover the run?
  • Tool ID - does the tool exist?
  • Version - does the requested version exist?

If any check fails, the request is rejected immediately with an error code. Your code does not run, and the rejected request is not charged.

3. Routing and run

If validation passes, the platform routes the request to a fresh, isolated environment for the requested version. Your handler runs with the event payload injected as the event argument, and your code produces a response object with a statusCode and a body.

The environment your tool runs in has its own resource limits - 512 MB memory, 300-second timeout, 2.0 CPU cores. See Run Environment for the full details.

4. Response and logging

Once your handler returns (or hits an error), the platform sends the response back to the caller and records the run - input, output, credits consumed, status. The record is immediately visible in your Analytics dashboard.

Error conditions

Not every run finishes successfully. The platform distinguishes:

  • 401 Unauthorized - the API key is missing or invalid. Rejected before any processing. Not charged.
  • 402 Payment Required - the organization doesn’t have enough credits. Blocked before run. Not charged. Top up your balance from Settings → Billing.
  • 404 Not Found - the tool ID or version doesn’t exist. Check the values from the tool’s detail page. Not charged.
  • 408 Timeout - your handler ran past the timeout. Run is terminated, caller gets a timeout response. Not charged.
  • 500 Handler Error - your handler threw an uncaught exception. The platform catches it, returns a 500, and logs the error. Charged, because your code did execute.

See the full Error Reference for runtime error shapes.

What you don’t manage

The platform abstracts away the operational layer so you can focus on building. You don’t manage:

  • Server provisioning or capacity planning
  • Scaling, load balancing, or concurrency limits
  • Isolation between users or organizations
  • Billing logic or run accounting
  • Logging and retention

Your job: write a handler that takes an event and returns a response.

  • Run Environment - resource limits and isolation for a single run
  • Storage - what persists between runs and what doesn’t
  • APIs - request and response format