Cache first. Money second.
One request path, two token storage modes, and a spending model with no surprises.
Every metric checks the snapshot store first
Positions, backlinks, competitors, SERP — if a snapshot exists, it's served instantly and free, with its date and age shown. If not, you see the exact price and confirm before anything is spent.
request → snapshot exists? ──yes──→ $0.00 + snapshot date
│
no
↓
price + confirmation → DataForSEO → $ your token
↓
raw response stored as a snapshot (next view is free)
↓
one row in your usage log History accumulates: every paid call becomes a dated snapshot, so trends and comparisons get richer over time without repeat spending.
Two ways to store your token
Your DataForSEO token is your money, so you decide where it lives. Both modes use the same snapshot store and the same personal usage log.
| server | browser | |
|---|---|---|
| where the token lives | in the database, encrypted with AES-GCM | only in your browser's localStorage |
| who calls DataForSEO | the LibertySEO server | your browser, directly (CORS is allowed) |
| what the server sees | the token, encrypted at rest | never sees the token |
| best for | teams, automation, MCP | keeping credentials strictly client-side |
Before saving, the token is validated with a free appendix/user_data ping. Errors are human-readable: wrong password, IP allowlist restriction (with the missing IP spelled out), or insufficient balance.
What gets stored
| store | contents |
|---|---|
| snapshots | raw DataForSEO responses (JSONB), each with its fetch date |
| usage log | who, when, which call, what it cost — per user |
| sites | your list of tracked domains with location and language |
| tokens | token mode; in server mode, the AES-GCM ciphertext |
Sign-in is email + password (bcrypt) or Google OIDC; sessions are HTTP-only cookies. Personal API tokens lseo_… for MCP and scripts are created and revoked in Settings.
Keeping spend predictable
Prices are shown before a call runs, with explicit confirmation. A monthly limit halts paid calls once reached; the usage report breaks spending down by day, endpoint and site. Your DataForSEO balance sits in the dashboard header — nothing spends silently.