Skip to content
EN
Get API key
Browse documentation

Get started

Agent trial and claiming

Try a Google search before signup, then connect an owner account to keep using the same CLI profile.

On this page

1. Check existing access

Run this free check in your agent's environment. If data.accessVerified is true and Google Search is permitted, reuse that access and skip to step 3. With no saved profile, continue to step 2. Resume pending or blocked access using the recovery section below.

Check this profile
flashdata auth status --json --non-interactive

Keep the same profile

Working access reports data.accessVerified: true, access: ready in data.identity.identity, and google_search in data.identity.permittedSources.

These commands use the default profile and work in Bash or PowerShell. For an existing named profile or custom state directory, append the same --profile NAME and --state-dir ABSOLUTE_PATH to every command, including those in a fresh terminal.

FLASHDATA_API_KEY overrides the saved key. Keep it unset when testing this profile's trial and handoff. Use the same OS user and preserve the private state directory; it holds credentials, the registration proof and run history.

Inspect credentialProtection in auth status. Windows uses DPAPI, macOS uses Keychain, and headless Linux may use an owner-only credential file. An available OS store can be required with --credential-store os.

Use an existing owner key instead

A person at a terminal can import a key through the hidden prompt below and skip trial registration and claiming. Agents should supply it on stdin with --api-key-stdin --non-interactive from their secret store; never put a key in arguments or chat.

If the profile already holds different access, review it before using auth login --replace. Importing another key is not the claim handoff. MCP OAuth is also a separate host connection.

Hidden key prompt · human terminal
flashdata auth login
flashdata auth status --json --non-interactive

2. Start one eligible trial

Run discover first. Check data.onboardingAvailable and the allowance in data.onboarding.trial. If onboarding is available, run init once for Google Search. The server checks eligibility; the CLI saves the temporary key without opening signup or submitting a query.

Check availability · free
flashdata discover --json --non-interactive
Start temporary access
flashdata init --name "Research assistant" --scopes google_search --json --non-interactive

Check the registration receipt

Expect ok: true, data.status: trial and google_search in data.connection.scopes. Read data.connection.trialExpiresAt and data.startingAllowanceCredits. The key is saved locally, not printed. If data.currentBalanceAvailable is false, rerun the free balance check before querying.

If setup already created access, reuse it. To label an agent's first registration, add --client codex --audience coding or --client openclaw --audience personal. Retain the exact input on a retry; labels do not grant permissions.

Trial allowance and limits

Request equivalents share the same starting credit balance; they are not remaining requests or independent quotas. Owner-only sources such as YouTube Download cannot spend trial credits.

LimitWhat to check
Credits / expiryCurrent defaults: 1 credit for 72 hours. Read discovery for the grant and lifetime; the receipt gives the expiry and granted sources.
Registration3 registrations per IP per 24 hours, shared by users of that IP. The global trial cap may also pause new registrations.
ConcurrencyKeep trial work sequential: one item per batch and one pending job. Check returned limits before submitting more.

3. Try one search

Preview first. Require data.estimateAvailable, an available google_search price in data.estimate.prices, and availableCredits covering estimatedCredits. Stop if a check fails. The preview is free; the next command submits one search.

Check balance and cost · no query
flashdata account balance --json --non-interactive
flashdata search "battery recycling" --num 5 --dry-run --json --non-interactive
One search · up to five results
flashdata search "battery recycling" --num 5 --run-id trial-search --json --non-interactive

Check the result

Expect ok: true and data.status: done. Read titles, links and snippets from data.results[].organic, and the charge from data.usage.credits. Empty organic results are valid. Before claiming, repeating this exact task with trial-search returns its saved result. Keep the profile and state, and retain any trial results you need.

Check the remaining balance · free
flashdata account balance --json --non-interactive

4. Keep access with an owner account

Claim before the trial expires if you want continued or recurring use. When the owner is ready, run this in the original profile. Share only data.claimUrl and data.confirmationCode with them; data.expiresAt gives the deadline.

The link lasts 15 minutes, or until the trial expires if sooner. Creating the link does not approve access or purchase credits.

Create a claim link when the owner is ready
flashdata auth claim --json --non-interactive

Approve in the browser

  1. The owner opens the link and signs in, or creates a new account and verifies email. A new signup resumes the claim after verification.
  2. Check the account shown on the claim page. For a different or new owner, use a separate browser session. The signed-in account is the account that will pay for later requests.
  3. Enter the eight-digit code on that page, review product permissions and shared-balance access, then approve. The owner handles signup, legal acceptance, email verification and consent.

Finish in the original terminal

After approval, run finish in the original profile within 24 hours. The CLI saves the owner key, verifies it in a fresh process and acknowledges installation. No key is copied from the browser.

Save and verify owner access
flashdata auth finish --wait --timeout 10m --json --non-interactive
Then check from a fresh terminal · same OS user and profile
flashdata auth status --json --non-interactive
flashdata account balance --json --non-interactive

Confirm the owner and balance

In auth status, verify the intended accountId and granted scopes, plus the fields below. Read the fresh balance separately; future requests spend the owner's shared credits. Unused temporary credits do not transfer. A new account follows normal signup eligibility; claiming adds no extra signup grant.

Claiming changes the billed account. For a new task under the owner, choose a new run ID. Reusing a trial run ID returns run_account_mismatch without submitting another query; it does not transfer that run to the owner.

Expected fields · response excerpt
{
  "ok": true,
  "data": {
    "accessVerified": true,
    "identity": {
      "identity": {
        "accountType": "owned",
        "access": "ready",
        "installed": true,
        "recurringAllowed": true
      }
    }
  }
}

Choose product permissions

The HTTP permission catalog separates trialEligible from ownerAllowed. Request only the sources needed by your task before the first registration. requestedScopes is the request; scopes is the key's current access. New products require an explicit grant.

Approval uses the owner's shared balance, including purchased credits. Source restrictions do not create a per-agent spending cap. MCP OAuth is a separate connection and does not claim this CLI profile.

Only need YouTube Download?

Use an owner key with youtube_download permission, import it, then configure destination storage. Download does not use temporary trial credits.

CLI 1.2.1 still requires a trial-eligible source for init. For Download-only onboarding before signup, use the HTTP claim flow in auth.md. Do not add an unrelated trial source just to bypass that client restriction.

Resume a stopped flow

What stoppedNext action
RegisterFor 429, wait for Retry-After. For a lost response, retry init with the same profile, proof and exact input. Keep existing state; do not switch IP or start a replacement trial.
SearchInspect trial-search below. A timeout does not prove that no work was accepted; do not change the run ID to force a retry.
Claim linkIf the link expired but the trial is valid, create a fresh link in the same profile when the owner is ready. Check the signed-in owner before approval.
HandoffAfter approval, rerun auth finish in the original profile within 24 hours. Pending approval, an interrupted wait or a lost acknowledgement does not require a new registration.
Expired / lost stateFor an expired trial or handoff, or a lost private state directory, use owner-approved reconnection or import an owner key.
Inspect the saved search · no new query
flashdata runs show trial-search --json --non-interactive