Skip to main content
Use a CSV when a GTM job starts with a list. The Play should preserve each row’s identity, output, and review state instead of treating the file as one opaque request.

​
Give each row a stable identity

Use a stable row key.
If you are outside the repository, create a small starter file:
If your file uses different column names, map them in your Play before you run it. Do not silently rename or discard source columns during a pilot.

​
Let the Play own the file contract

A Play that declares input.csv can receive a staged CSV through --csv and read it with ctx.csv(input.csv). --file remains a CLI flag, so a Play that declares input.file must receive that value through --input instead. The maintained example at docs-examples/sdk-v2/lead-email-waterfall.play.ts shows a file-backed dataset that enriches and validates one row at a time. Use Write Plays to change its business logic; this page owns the operational procedure for a file.

​
Pilot it first

Choose a small representative set, not only the easiest rows. Include the input conditions that can change coverage or cost, such as geography, company size, available identifiers, and seniority.
After the run completes, set RUN_ID to the run ID it printed, then export the same run:
Inspect /tmp/leads-pilot-enriched.csv. You want the original columns plus the email and validation columns added by the Play. Keep rows with missing data or errors so they can be reviewed instead of disappearing from the output.

​
Verify a tool contract before adding it

A tool name does not define its payload or response structure. Before you add a provider step, examine these items:
  • The live schema
  • The price
  • The connection state
  • The result getters
  • The limits
For example, inspect a known email-validation tool before you add it:
Use declared getters from tools describe when they match the pilot. If the shape is unknown, keep the raw result for that pilot and do not scale until you know which output field your Play depends on. Use deepline billing balance --json before and after the pilot. Calculate the balance difference. A composed Play can put provider charges in child runs, so do not use only the parent run to measure cost.

​
Keep bulk data in files

Use Play input for control parameters and file references. Do not pass a full spreadsheet as inline JSON through --input. Inline submitted JSON has a hard 1 MiB ceiling. Use a staged CSV and ctx.csv(input.csv) for row data so large inputs stay readable and resumable. The full-file command below passes the CSV through --csv.

​
Run the full file

After the completed run ID is in RUN_ID, export it with deepline runs export "$RUN_ID" --out leads-enriched.csv.

​
Why this matters

ctx.dataset makes every row resumable. If one row fails, you do not need to rerun the whole list blindly. If a row is missing required input, keep it in the output and mark it for review instead of deleting it silently. For scheduled refreshes and stale-result policy, use Webhooks and schedules with the exact staleAfterSeconds contract in SDK reference.