Error Handling & Async Behavior

Scans and campaigns execute asynchronously. A success response means the job is queued, not completed. You must poll for results.

The Async Scan Pattern

This is the most critical pattern in the API. When you submit a scan, the API queues it for processing and returns immediately. You then poll a separate endpoint until the results are ready.

Submit the Scan

Call POST /v2/run-scan/ with your scan parameters. A response with "success": true and the message "Scan submitted successfully" means the scan is queued, not completed. This is the expected response — it is not an error.

Poll for Results

Call POST /v1/reports/ filtered by placeId to check if the report has appeared. Use a lightweight fieldmask to keep polling fast:

fieldmask=report_key,date,keyword,location.name,arp,atrp,solv

Repeat every 10–15 seconds until your report appears in the response.

Retrieve the Report

Once the report appears, call POST /v1/reports/{report_key}/ with your full analysis fieldmask to get the complete scan data.

NEVER retry run-scan if you received "success": true. The scan is already queued and retrying would consume additional credits. If the report doesn't appear after 4–5 polling attempts, check localfalcon.com/reports directly.

Campaign Async Pattern

Campaigns follow the same async pattern but with longer timeframes because they trigger multiple scans.

  • POST /v2/campaigns/run returns success immediately once the campaign is submitted.
  • Campaigns trigger multiple scans across locations and keywords — they can take minutes to hours to complete.
  • Poll POST /v1/campaigns/ or POST /v1/reports/ to check for results.
  • Never retry run-campaign after a success response — retrying would consume additional credits.
  • After 4–5 polling attempts, stop polling and check the dashboard instead.

Eager Mode (Non-Google Platforms)

The behavior of POST /v2/run-scan/ depends on the platform:

  • Google scans (platform: "google") wait for results before responding, behaving more synchronously.
  • Non-Google platforms (apple, gaio, chatgpt, gemini, grok, aimode) use eager mode — the API returns immediately and the scan processes in the background.

For eager-mode scans, poll POST /v1/reports/ filtered by placeId to find the completed report, just like the standard async pattern above.

Rate Limiting

The API allows a maximum of 5 requests per second. If you exceed this limit, you will receive a 429 response.

Retry with exponential backoff:

  1. Wait 1 second, then retry.
  2. Wait 2 seconds, then retry.
  3. Wait 4 seconds, then retry.

Stop after 3 retries. Retryable errors include network errors, timeouts, and 5xx server responses.

Response Format

All API responses follow this structure:

{
  "code": 200,
  "success": true,
  "message": false,
  "data": { ... }
}
Code Success Meaning
200 true Request completed successfully
200 true Scan/campaign submitted (async — poll for results)
400 false Bad request — check parameters
401 false Invalid or missing API key
402 false Insufficient credits
404 false Report or resource not found
429 false Rate limited — wait and retry
500 false Server error — retry with backoff

Common Gotchas

  1. "success": true doesn't mean the scan is done — It means the scan was submitted. Poll for the report.
  2. Retrying costs credits — Never retry run-scan or run-campaign after a success response.
  3. Campaign scans don't create separate trend/location/keyword reports — All that data is consolidated in the Campaign Report.
  4. data_points is stripped by default — Don't expect it unless you explicitly request it in the fieldmask.
  5. Date format is MM/DD/YYYY — Not ISO 8601. All date parameters use this format.
  6. Omit unused parameters — Don't pass null or empty strings for optional parameters you're not using.

Timeouts

Operation Timeout
Standard API calls 30 seconds
Grid searches, campaign reports, keyword-at-coordinate 60 seconds
Large campaign runs Minutes to hours (poll, don't wait)

Next Steps