Exporting your data

Everything iSearchFrom measures for you can leave the platform in a documented, stable shape. Export a file once when you need it, or save a destination that keeps delivering new data on a schedule — to your team’s inboxes, your own endpoint, a Google Drive folder, a storage bucket, an SFTP server, a data warehouse or a spreadsheet.

What you can export

Data is exported as datasets — one table-shaped stream per kind of measurement:

Dataset	What each row is
position_tracker.results	A ranking position found, per keyword and domain
position_tracker.checks	A keyword check, including checks that failed
ad_tracker.ads	A paid ad seen, per keyword
maps.results	A place ranked, per keyword and grid point
marketplace.results	A product listed, per keyword and marketplace
ai_visibility.responses	A prompt answered, with how your brand fared
ai_visibility.mentions	A brand named in an answer — yours or a competitor’s
search_history	A search run with the Search Engine Proxy or Direct Search
search_history.results	A result on a page fetched by a Search Engine Proxy search
alerts	An alert raised on one of your campaigns

Every row of every dataset starts with the same two columns:

• row_id — a stable id, unique within its dataset. If a row ever reaches you twice, it has the same row_id both times, so you can always de-duplicate on it.
• measured_at — when the value was measured, in UTC. Warehouses partition on it.

The full column list for every dataset is in the dataset reference.

Columns are a contract

Columns are only ever added — never renamed, removed or retyped. Each dataset carries a schema_version that goes up when it gains a column. Build your pipelines to tolerate new columns and they will not break.

Choosing what goes into an export

An export is a selection:

• Scope — the whole organization, or up to 50 specific projects.
• Datasets — one or more of the datasets above, each picked once.
• Filters per dataset:
  • Campaign datasets — specific campaigns (up to 200 per dataset), or all of them. “All” is resolved at every run, so a campaign created later joins by itself.
  • search_history — only proxy or only direct searches, and/or only saved searches.
  • search_history.results — only saved searches.
  • alerts — by tool, by severity, and/or by campaign.
• Columns per dataset — every column, or only the ones you pick. See choosing columns.

You can only export what you can already see. Each dataset needs the matching read permission — Position tracker, Maps, Search history and so on — and the tool must be on your plan. With project-level access, “the whole organization” means the projects you have access to.

Choosing columns

By default an export carries every column of each dataset. To send fewer, press Choose columns next to a dataset and untick what you don’t need; Export every column again undoes it.

• row_id and measured_at are always included, whatever you pick, so every file can still be de-duplicated and partitioned.
• Picked columns keep their dataset order.
• With a pick, columns the dataset gains later are not added — the export sends exactly what you chose. With no pick, new columns arrive by themselves.

What a pick means at each destination:

Destination	With picked columns
Files (download, email, bucket, Google Drive, SFTP)	Each file holds only the picked columns. A bucket’s manifest lists them
Webhook	Each row object carries only the picked columns
BigQuery	Tables keep every column; the columns you left out are NULL in the rows loaded
Google Sheets	A tab holds the picked columns. Changing the pick later starts a new tab, e.g. alerts (2)
SQL files	CREATE TABLE names only the picked columns — see changing columns

One-off downloads

The quickest export: choose a selection, a time window and a format, and download the result.

• Window — a fixed date range, or the last N days; at most 366 days either way.
• Format — any file format your plan includes: CSV, Excel, JSON Lines, SQL or Parquet.
• Result — one file per dataset. A dataset with no rows in the window still gets a file (in CSV, just the header row).

Only the person who requested a download can fetch its files. Each download link is valid for five minutes — request a fresh one whenever you need it. The files themselves are kept for 7 days.

Destinations

A destination is a saved export: where the data goes, what goes into it, and optionally a schedule.

Destination	Formats	Best for
Download	Every file format	A file right now; one-off only, never saved
Email	Every file format	Regular files for teammates who don’t run a pipeline
Webhook	JSON (signed batches)	Feeding your own service, an automation tool, or a queue
Google Sheets	Rows in a spreadsheet	Lightweight reporting, charts and sharing with people outside the platform
Google Drive	Every file format	Dated files in a Drive folder, for people who work from Drive
Cloud storage bucket	Parquet, CSV, JSON Lines, SQL	A data lake, and the source for Snowflake, Redshift, Databricks and DuckDB
BigQuery	Loaded as tables	Querying and joining your data in Google’s warehouse
SFTP server	Every file format	Dropping files where an existing import job or partner already looks

A cloud storage bucket can be Amazon S3, Google Cloud Storage, Cloudflare R2, Wasabi, Backblaze B2, DigitalOcean Spaces, MinIO or any other S3-compatible store — see providers.

An email destination sends to organization members (up to 20). The email carries a link to the files in iSearchFrom — never the file itself — so a forwarded message opens nothing without a sign-in. A recipient only gets the link while they can still see all of the data in the export themselves. Files are kept for 7 days, like downloads.

Before saving a webhook, bucket, BigQuery, Google Sheets, Google Drive or SFTP destination you can press Test connection: a small check that confirms the address, credentials and permissions work. For an SFTP server it also shows the server’s host key, so you can check it and pin it.

Formats

Every file-based destination lets you choose the file format:

Format	What it is	Use it for
CSV	Comma-separated text with a header row	Spreadsheets, and any tool that imports CSV
Excel	An .xlsx workbook, one sheet per dataset, with real numbers and dates	People who open the file in Excel, Numbers or Google Sheets
JSON Lines	One JSON object per line	Developers, scripts and log pipelines
SQL (PostgreSQL)	A script that creates the table and inserts the rows; also SQLite and DuckDB	Loading straight into your own database with psql, sqlite3 or duckdb
SQL (MySQL)	The same, in MySQL and MariaDB syntax	Loading with mysql
Parquet	A compressed, typed columnar file	Data lakes and warehouses: Snowflake, Redshift, Databricks, BigQuery, DuckDB, pandas

Which destinations take which format:

Destination	CSV	Excel	JSON Lines	SQL	Parquet
Download, Email, Google Drive, SFTP	✓	✓	✓	✓	✓
Cloud storage bucket	✓		✓	✓	✓

A webhook always receives JSON, BigQuery always loads rows into tables, and Google Sheets always writes rows into tabs — there is no format to choose for those.

CSV, JSON Lines and SQL files are gzipped (.gz) in buckets, on Google Drive and on SFTP servers; downloads arrive uncompressed. Excel and Parquet compress themselves and are never gzipped again. Which formats you can choose also depends on your plan. The formats guide covers each format in depth, including how to load SQL files.

Starter templates

When you add a destination, Start from a template fills in the destination, data, format and schedule for a common setup. Everything stays editable before you save.

Template	Delivers	Format	When
Weekly rankings by email	Position tracker checks to your team	Excel	Mondays at 07:00
Daily rankings in Google Sheets	Every keyword check appended to a spreadsheet	—	Every day at 06:00
Weekly AI visibility to Drive	AI answers and brand mentions	Excel	Mondays at 07:00
Alerts to a webhook	New alerts, for Slack, Zapier or your own service	JSON	Every hour
Sync to your data lake	All tracking data to your bucket	Parquet	Every hour
Sync to BigQuery	All tracking data loaded into your warehouse	—	Every hour

Only templates your plan and role allow are shown. Or choose where to send it and set everything up yourself.

Who a destination runs as

A saved destination acts with the access of the member who last saved it. Every run re-checks that access: a dataset that member can no longer read is skipped (the run lists it and why), and if they leave the organization the destination stops until someone else edits and saves it. Whoever saves a destination becomes the member it runs as.

Schedules and incremental delivery

A destination can run on a schedule — every day or every week at the time and in the time zone you choose, or every hour (through the API, any cron expression) — or Only when I run it, when someone presses Run now. Team schedules run at most daily. Agency adds hourly schedules for destinations a machine reads: webhooks, cloud storage buckets, BigQuery and SFTP. An hourly destination runs at a minute we pick for it, so syncs across the platform are spread over the hour.

Scheduled destinations are incremental: each run delivers what is new since the last successful run, so your destination builds up a complete history without repeats. A scheduled run that finds nothing new sends nothing: no empty file, email or webhook call. It still shows in Recent exports as “Nothing new”. A run you start yourself always delivers, even when it is empty.

• The first run reaches back as far as you choose when saving the destination — 7 days by default, up to 365.
• A five-minute settle lag. Each run stops five minutes before it starts, so data still being written is picked up by the next run instead of being missed.
• Campaign rows arrive with their run. Rows from a campaign run are exported once that run has finished, all together — a long run is never split across two exports or missed between them. Search history and alerts are exported by the time they were created.
• One run at a time per destination. If the previous run is still going, the next scheduled one waits for the following slot.

Run now runs the same incremental export immediately. It can also take a fixed date range — a backfill — to re-send an older window. A backfill does not move the destination’s incremental position, so the schedule carries on where it was; the rows it re-sends can repeat rows the destination already has. A backfill that fails leaves the destination’s status alone; only the incremental runs decide whether it needs attention.

If a dataset in the selection stops being readable — the member it runs as lost access, or the plan dropped that tool — incremental runs stop with Needs attention instead of skipping it, so no window is lost. Restore the access or the plan and resume it, or remove that dataset and save; it carries on from where it stopped.

De-duplicate on row_id

Delivery is at least once. A backfill, or a run that failed half-way and was then covered by the next one, can deliver a row a second time. It always carries the same row_id, so key your tables and upserts on (dataset, row_id). This matters most where files and rows are only ever added — BigQuery tables, bucket and SFTP folders, Google Drive, and webhook receivers. Google Sheets tidies its own tab after a retry.

Stopping an export

You can cancel an export that is still running. It stops before its next batch; anything it had already delivered stays delivered.

When something goes wrong

Temporary problems — the destination timing out, a rate limit, a server error on its side — are retried automatically. A run that still fails is marked failed with an error code, and nothing is lost: the destination’s incremental position only moves on success, so the next run delivers the same data again.

A destination has a status:

Status	Meaning	What resumes it
Active	Running normally	—
Paused	Paused by a person, or automatically after 10 failed runs in a row	Resume it
Needs attention	The destination refused the data — a wrong bucket, a deleted sheet, a rejected request	Fix the settings and save; it runs again
Needs reconnect	The connected Google account must be connected again	Reconnect it under Settings → Integrations; the destination resumes by itself
Suspended	Your plan no longer includes it, or the member it runs as has left	Resumes by itself when the plan allows it again; for a departed member, edit and save it

When a destination needs a person — or after three failed runs in a row — the organization’s owners and the member it runs as are notified in the app and by email, at most once a day per destination.

Error codes

Each failed run, test and skipped dataset reports one of these codes:

Code	What happened	What to do
destination_unreachable	The destination could not be reached, timed out, or had a server error	Usually temporary and retried automatically. If it persists, check the URL or endpoint is public and up
destination_rejected	The destination refused the data	Check the destination’s settings; for a webhook, your endpoint answered with a 4xx or a redirect
access_denied	Credentials were refused, or the member lost access to the selected data	Check keys and permissions at the destination, or the member’s roles in iSearchFrom
reconnect_required	The connected Google account’s access expired or was revoked	Reconnect it under Settings → Integrations
not_found	The bucket, dataset, spreadsheet or endpoint no longer exists	Recreate it, or point the destination somewhere that exists
too_large	The export has more rows than one run may carry on your plan	Narrow the selection or the window; split a large backfill into shorter ranges
host_key_changed	An SFTP server presented a different host key than the one pinned	If the change was expected, check the new key and pin it — see host keys
sheet_full	The spreadsheet reached Google’s 10-million-cell limit	See Google Sheets limits
selection_empty	Nothing in the selection can be exported any more	Check the campaigns and projects still exist and the member can read them
plan_limit	The current plan does not include this destination, format or schedule	Change the destination or the plan; suspended destinations resume by themselves on upgrade
owner_removed	The member the destination runs as has left the organization	Edit and save the destination as a current member; it runs again
internal_error	Something went wrong on our side	Retried automatically; contact support if it keeps happening

Plans and limits

Exports are part of the Team and Agency plans. Starter and Pro don’t include exports.

	Team	Agency
Destinations	Download, Email, Webhook, Google Sheets, Google Drive	Everything in Team, plus cloud storage buckets, BigQuery, SFTP
Formats	CSV, Excel, JSON Lines, SQL (PostgreSQL and MySQL)	Everything in Team, plus Parquet
Schedules	Daily or weekly	Adds hourly for webhooks, buckets, BigQuery and SFTP
Saved destinations	10	Unlimited
Rows per run	250,000	1,000,000

A run with more rows than your plan allows fails with too_large — narrow the selection, or split a backfill into shorter windows.

After a downgrade nothing you set up is deleted: destinations the new plan does not include are suspended with their settings intact, and resume by themselves after an upgrade. If you are over the plan’s destination count, the oldest destinations keep running.

Permissions

Exports have their own Export permission in roles:

Action	Allows
Read	One-off downloads of data you can already see; seeing your own exports
Create	Saving destinations and testing connections
Update	Editing, pausing and resuming destinations, Run now, rotating a webhook secret, seeing and stopping everyone’s exports
Delete	Deleting a destination and its run history

Owners and admins hold all four. Members can download what they can see; sending data out of the platform on a schedule is an administrative decision.

Retention

• Downloadable files (downloads and email exports) are kept for 7 days.
• Run history is kept for 180 days.
• Data already delivered to your destination is yours — iSearchFrom never deletes or changes it.

Using the API

The export endpoints live under https://api.isearchfrom.com/v1/organizations/{organizationId}/exports:

Method	Path	Does
GET	/catalog	Datasets, destinations and formats available to you, and your plan’s limits
POST	/runs	Start a one-off download
GET	/runs, /runs/{runId}	List exports, or get one
GET	/runs/{runId}/download?dataset=…	A five-minute link to one dataset’s file
POST	/runs/{runId}/cancel	Stop an export
GET	/destinations, /destinations/{id}	List destinations, or get one
POST	/destinations	Save a destination
POST	/destinations/test	Test connection details before saving them
POST	/destinations/{id}/test	Test a saved destination
PATCH	/destinations/{id}	Change a destination
PATCH	/destinations/{id}/status	Pause or resume
POST	/destinations/{id}/runs	Run now, optionally with a fixed backfill window
POST	/destinations/{id}/rotate-secret	Replace a webhook’s signing secret
DELETE	/destinations/{id}	Delete a destination and its run history

Signed-in members only

Export endpoints accept a signed-in member’s session, not API keys. A saved destination acts as the member who saved it, and an API key is not a member.

Related docs

• Dataset reference
• File formats
• Webhook destination
• Cloud storage buckets
• BigQuery
• Google Sheets
• Google Drive
• SFTP server
• Warehouse recipes
• Roles and Permissions