# JSON to CSV Converter: Nested JSON to One CSV, No Start Fee (`ucchiii/json-to-csv`) Actor

Convert a JSON or NDJSON file (public URL) or an Apify dataset into one CSV file with a download link. Nested objects become dot columns like address.city, arrays become JSON text, and you can pick and order the columns. Empty input = free demo.

- **URL**: https://apify.com/ucchiii/json-to-csv.md
- **Developed by:** [Actor Factory](https://apify.com/ucchiii) (community)
- **Categories:** Developer tools, Automation, Integrations
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.03 / 1,000 converted rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

**JSON to CSV converter: turn a JSON file, an NDJSON file or an Apify dataset into one clean CSV file with a download link.**

Paste a link to a JSON file (or pick a dataset), press **Start**, and get a single `.csv` file you can open in Excel, Google Sheets, a database or a script. Nested objects become dot columns (`customer.address.city`), arrays are kept as JSON text in one cell, and you decide which columns go in and in what order. You pay per converted row only — no start fee, no monthly rent.

**Try it free:** leave the input empty and press **Start** — 4 built-in sample orders are converted to `sample-orders.csv` (not charged; the summary item carries `_demo: true`).

### What you get

Input (one JSON row):

```json
{"orderId": "A-1001", "customer": {"company": "Northwind Traders", "address": {"city": "Seattle"}}, "total": 1249.5, "paid": true, "tags": ["priority", "gift"]}
```

CSV file:

| orderId | customer.company | customer.address.city | total | paid | tags |
|---|---|---|---|---|---|
| A-1001 | Northwind Traders | Seattle | 1249.5 | true | \["priority", "gift"] |

- **One CSV file** in the run's key-value store, with a signed **download link**.
- **One summary item** in the dataset: file name, download link, rows, columns, size in bytes, and any requested columns that were not found.

### How to use

1. **JSON or NDJSON file URL** — a public link to a JSON array (`[{...}, {...}]`), an object that holds one array (`{"items": [...]}`, typical for API responses) or NDJSON / JSON Lines (one object per line). **Or** pick an **Apify dataset**, for example the results of a scraper run.
2. Optional **Columns** — the columns you want, in the order you want. `customer` keeps every `customer.*` column. A name that is not in the data is still written as an empty column, so every file you make has the same header.
3. Optional: **Delimiter** (comma, semicolon, tab), **UTF-8 BOM for Excel**, **Formula-safe text** (on by default), **Output file name**.

```json
{
  "fileUrl": "https://example.com/exports/orders.json",
  "columns": ["orderId", "customer.company", "total", "tags"],
  "delimiter": "comma",
  "excelBom": true,
  "fileName": "orders-2026-11"
}
```

### Output details

- **Columns** follow the order they first appear in the data, unless you list them in **Columns**.
- **Values**: numbers stay as written (`1249.5`, `-3`), `true`/`false` stay as text, `null` and empty objects or arrays give an empty cell. Arrays are written as JSON text: `["priority", "gift"]`.
- **Formula-safe**: text that starts with `=`, `+`, `@` (or `-` when it is not a number) gets a leading apostrophe, so a value like `=HYPERLINK(...)` never runs in Excel or Google Sheets. Turn it off to keep text byte-for-byte.
- **Line ends** are CRLF (`\r\n`), as RFC 4180 and Excel expect. The file is UTF-8.
- **STATS** record: source, rows, column names, file size, rows charged and notes.

### Limits (cannot be raised by input)

- JSON arrays and NDJSON files up to **300 MB**; a file that is one object wrapping the rows (`{"items": [...]}`) up to **20 MB** — use an array or NDJSON for bigger data.
- **1,000,000 rows** per run, **1,000 columns** in the CSV, CSV file up to **150 MB**. Use **Columns** to keep fewer columns.
- Files must be UTF-8 (the JSON standard). Public files only, no login. Links to internal network addresses are blocked.
- If the maximum charge you set for the run is lower than the number of rows, the run stops **before anything is charged** and tells you how many rows it can afford — you never get a half-finished CSV.

### Pricing

Pay per event: **$0.00005 per converted row** ($0.05 per 1,000 rows), with no start fee. A 2,000-row file costs $0.10. Failed runs, inputs over a limit and the demo are free.
Store discounts apply automatically: BRONZE −10%, SILVER −20%, GOLD −30%.
On the Apify Free plan, the $5 of monthly platform credit covers about 100,000 rows a month.

### FAQ

**Can I get the rows in the dataset instead of a file?** This Actor makes one CSV file. If you want flat rows in a dataset (to download as CSV, Excel or JSON from Apify yourself, or to feed another Actor), use the Flatten JSON Actor from the same developer.

**My JSON is one big object, not a list.** If it holds exactly one list of objects (like `{"total": 120, "data": [...]}`), that list becomes the rows. Any other object becomes a single row.

**Accents look wrong in Excel.** Turn on **Add a UTF-8 BOM for Excel**. In many European Excel versions also choose the **semicolon** delimiter.

**Does it change my data?** Only the shape: nested names are joined with dots, and (with formula-safe on) risky text gets an apostrophe. Values are not rounded or re-formatted.

If this Actor saved you time, a rating on the Store helps others find it.

### More tools from the same developer

- [CSV / XLSX Converter](https://apify.com/ucchiii/csv-xlsx-converter) — convert CSV, TSV, Excel XLSX, JSON and NDJSON files or Apify datasets into each other
- [Excel to JSON](https://apify.com/ucchiii/excel-to-json) — turn Excel (XLSX) sheets into JSON rows, or a JSON file into an Excel sheet
- [Dataset Transform](https://apify.com/ucchiii/dataset-transform) — flatten, filter, rename and convert any Apify dataset, export CSV / JSON / JSONL with a link

# Actor input Schema

## `fileUrl` (type: `string`):

Public http(s) link to a JSON array, an object holding one array (like {"items": \[...]}) or NDJSON (one JSON object per line), up to 300 MB. Use this OR an Apify dataset. Leave both empty for a free demo on built-in sample orders.

## `datasetId` (type: `string`):

Dataset to convert, for example the results of a scraper run. You can paste a dataset ID or a dataset URL from Apify Console.

## `columns` (type: `array`):

Keep only these columns, in this order. Use flattened names like address.city; a parent name like address keeps all its address.\* columns. A name that is not in the data stays as an empty column. Empty = all columns, in the order they first appear.

## `delimiter` (type: `string`):

Character between the values. Default: comma.

## `excelBom` (type: `boolean`):

Starts the file with a byte-order mark so Excel shows accents and non-Latin text (é, ü, 東京) correctly when you double-click the file. Leave off for databases and scripts.

## `formulaSafe` (type: `boolean`):

Puts an apostrophe before text that starts with = + @ (or - when it is not a number), so Excel and Google Sheets never run it as a formula (CSV injection). Numbers are not changed. Turn off to keep the text exactly as is.

## `fileName` (type: `string`):

Name of the CSV file, for example 'products' gives products.csv. Empty = taken from the source file name or dataset ID.

## Actor input object example

```json
{
  "delimiter": "comma",
  "excelBom": false,
  "formulaSafe": true
}
```

# Actor output Schema

## `summary` (type: `string`):

One item: the CSV file name, its download link, rows, columns, size, and any requested columns that were not in the data.

## `files` (type: `string`):

The key-value store that holds the .csv file.

## `stats` (type: `string`):

Record STATS: source, rows, column names, file size, rows charged and notes.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ucchiii/json-to-csv").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("ucchiii/json-to-csv").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call ucchiii/json-to-csv --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ucchiii/json-to-csv"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/koW7hslxxPckgeQFA/builds/A32C5810JImNPYjiM/openapi.json