SFTP server

An SFTP destination uploads files to your own server over SFTP: one file per dataset per run, in the format you choose. Use it when an existing import job, an ETL tool or a partner already picks files up from a server. SFTP destinations are part of the Agency plan.

Settings

Setting	Notes
Host	The server’s host name or IP address. It must be reachable from the internet.
Port	22 by default.
Username	The account to sign in as.
Folder on the server	An absolute path starting with /, e.g. /uploads/isearchfrom. It must already exist.
Sign in with	Password, or Private key.
Password	Stored encrypted and never shown again.
Private key	The full private key, in OpenSSH or PEM format, without a passphrase. Stored encrypted.
Host key fingerprint	Optional. The server’s key, like SHA256:…. See host keys.
Format	CSV, Excel, JSON Lines, SQL or Parquet, as your plan allows.

When you edit a saved destination, leave the password or private key empty to keep the saved one.

Test connection signs in, checks that the folder can be read, and shows The server’s key.

We recommend a dedicated account that can only write to the export folder — a chrooted SFTP-only user is ideal. For key sign-in, create a key pair just for iSearchFrom and add its public key to that account’s ~/.ssh/authorized_keys:

ssh-keygen -t ed25519 -N "" -C isearchfrom-exports -f isearchfrom_exports
# Paste the contents of isearchfrom_exports (the private key) into iSearchFrom.
# Add isearchfrom_exports.pub to the server account's ~/.ssh/authorized_keys.

Host keys

A server proves who it is with its host key. Pinning that key means a run only ever uploads to your real server — never to anything that has taken over its address.

• Pin it yourself — paste the fingerprint into Host key fingerprint. On the server:

  ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

  or from any machine that can reach it:

  ssh-keyscan -p 22 sftp.example.com | ssh-keygen -lf -

  Use the SHA256:… value for the key type your server offers (usually ED25519).

• Pin from the test — press Test connection, compare The server’s key with the one your server administrator gives you, and press Pin this key.

• Trust on first use — leave the field empty. The key the server presents on the first successful connection is pinned automatically.

From then on, a server presenting a different key is refused: the run fails with host_key_changed and the destination needs attention. If the key changed on purpose — a rebuilt or migrated server — check the new key, put it in Host key fingerprint and save. If you didn’t expect a change, find out why before trusting the new key.

What gets written

Files go straight into the folder, named after the dataset, the day and the run:

<folder>/<dataset>_<YYYY-MM-DD>_<run_id>.<extension>

For example:

/uploads/isearchfrom/position_tracker-results_2026-09-30_0199a7c2-5b1e-7c3a-9f10-3d2b8e6a4c11.csv.gz
/uploads/isearchfrom/alerts_2026-09-30_0199a7c2-5b1e-7c3a-9f10-3d2b8e6a4c11.csv.gz

• <dataset> is the dataset id with . replaced by -; the date is the UTC day the run’s window ends.
• CSV, JSON Lines and SQL files are gzipped (.gz); Excel and Parquet files are not.
• Files appear complete. Each file is uploaded under a temporary hidden name — .<name>.part — and renamed to its real name only once it is complete. Whatever picks files up never reads half a file; just have it ignore names starting with . or ending in .part.
• A retried run replaces its own file instead of adding a second copy.

iSearchFrom never deletes delivered files. Clear out or move old files on your side.

Network and security

• The server must be reachable from the internet. Private and internal addresses — 10.x, 192.168.x, localhost and the like — are refused.
• Passwords and private keys are encrypted at rest and never shown again after saving.

Duplicates

Each run delivers only what is new since the last successful one. A backfill with Run now re-sends an older window as new files, which can repeat rows you already have. Every row keeps its row_id — de-duplicate on it when you load.

Troubleshooting

Code	Likely cause
host_key_changed	The server presented a different host key than the pinned one. See host keys.
access_denied	Wrong username, password or key, or the account can’t write to the folder.
not_found	The folder doesn’t exist. Create it on the server, or fix Folder on the server.
destination_unreachable	The host name doesn’t resolve, the port is closed, or the address is private. Temporary errors retry.

See all error codes.

Related docs

• Exporting your data
• File formats