# JSON to CSV Converter (`maximedupre/json-to-csv-converter`) Actor

Turn a JSON object or collection into a CSV or TSV file. Use direct JSON, a URL, or an Apify dataset, then flatten nested fields, choose columns, and get the complete file with structured rows.

- **URL**: https://apify.com/maximedupre/json-to-csv-converter.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Developer tools, Automation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.75 / 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.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### 🧾 Move JSON into a CSV or TSV file

JSON to CSV Converter helps developers, analysts, and automation builders turn one JSON object or a collection of records into a complete CSV or TSV file. It returns a file link, a conversion summary, and structured dataset rows, so you can move JSON into Excel or another data workflow.

**Use cases**

- Move JSON into Excel with [**JSON to CSV in Excel**](https://apify.com/maximedupre/json-to-csv-converter/examples/json-to-csv-in-excel).
- Follow a guided conversion with [**How to convert JSON to CSV in Excel**](https://apify.com/maximedupre/json-to-csv-converter/examples/how-to-convert-json-to-csv-in-excel).
- Download the finished file with [**JSON to CSV Converter Download**](https://apify.com/maximedupre/json-to-csv-converter/examples/json-to-csv-converter-download).
- Use a browser-based path with [**JSON to CSV Converter Online**](https://apify.com/maximedupre/json-to-csv-converter/examples/json-to-csv-converter-online).
- Create a CSV from JSON with [**JSON to CSV Online**](https://apify.com/maximedupre/json-to-csv-converter/examples/json-to-csv-online).

#### 📊 Converted files, summaries, and rows

After a run, the Actor returns a complete CSV or TSV file link, file format, conversion status, row and column counts, and column names. It also saves structured dataset rows with `rowNumber` and a `values` object keyed by the output columns.

#### ▶️ Run one JSON conversion

Each run handles one conversion request.

1. Choose **Direct JSON**, **JSON URL**, or **Platform dataset** in `Target`.
2. Paste one JSON object or an array of JSON objects, enter a URL that returns one object or array, or choose the Apify dataset to convert.
3. Choose how to handle nested objects and arrays, select fields, and set the output format and delimiter.
4. Run the Actor, then use the file link or dataset link in the output.

Leave `maxRecords` empty to return all available results until the source is exhausted.

#### ⚙️ Input

Choose one source. Fields in other `Target` sections are ignored.

**Input fields**

| Field | Type | What it does |
| --- | --- | --- |
| `target` | string | Selects the source: `direct`, `url`, or `dataset`. |
| `jsonInput` | object or array | Supplies one JSON object or an array of JSON objects for `direct`. |
| `jsonUrl` | string | Supplies one HTTP or HTTPS URL that returns one JSON object or an array of JSON objects for `url`. |
| `datasetId` | string | Selects the Apify dataset that contains JSON records for `dataset`. |
| `nestedValueMode` | string | Chooses `flatten` for path-based columns or `preserve` for JSON in one cell. |
| `keySeparator` | string | Sets the text between parts of flattened keys. It is used when nested objects are flattened. |
| `arrayValueMode` | string | Chooses `rows` to create rows from array items or `cells` to keep array items in one cell. |
| `includeFields` | array of strings | Lists field names to export. An empty list includes all fields. |
| `excludeFields` | array of strings | Lists field names to leave out after `includeFields` is applied. |
| `maxRecords` | integer | Sets an optional source-record cap. Leave empty to return all available results until the source is exhausted. |
| `outputFormat` | string | Chooses `csv` or `tsv` for the output file. |
| `columnDelimiter` | string | Sets the text between columns. A comma is typical for CSV and a tab for TSV. |
| `includeHeaders` | boolean | Adds the column names as the first row when `true`. |
| `nullValue` | string | Sets the text used for null or missing values. |

**Example input**

This is the public input from a successful current-beta default run:

```json
{
  "target": "direct",
  "jsonInput": [
    {
      "sku": "NB-001",
      "name": "A5 notebook",
      "price": 12.5,
      "inStock": true
    },
    {
      "sku": "PN-002",
      "name": "Blue pen set",
      "price": 6.75,
      "inStock": true
    }
  ],
  "nestedValueMode": "flatten",
  "keySeparator": ".",
  "arrayValueMode": "cells",
  "outputFormat": "csv",
  "columnDelimiter": ",",
  "includeHeaders": true,
  "nullValue": ""
}
```

#### 🧾 Output

The run output has a conversion summary. The default dataset has one structured row for each converted output row.

**Run summary**

| Field | Type | What it does |
| --- | --- | --- |
| `status` | string | Shows whether the conversion finished. |
| `fileUrl` | string | Links to the complete CSV or TSV file in Apify storage. |
| `fileFormat` | string | Shows whether the file is CSV or TSV. |
| `datasetUrl` | string | Links to the converted rows in the default dataset. |
| `rowCount` | string | Gives the number of converted output rows. |
| `columnCount` | string | Gives the number of columns in the converted file. |
| `columns` | string | Gives the output column names in file order. |

**Dataset rows**

| Field | Type | What it does |
| --- | --- | --- |
| `rowNumber` | integer | Gives the position of this converted row in the output. |
| `values` | object | Holds the values for this row. Its keys are the output column names. |
| `values.<column>` | JSON value | Holds the value for one output column. Column names and value types come from the converted source data. |

**Example dataset row**

This complete row comes from a successful current-beta run that used `::` as the key separator and expanded array items into rows:

```json
{
  "rowNumber": 1,
  "values": {
    "orderId": "ORD-100",
    "customer::name": "Ada",
    "items::sku": "NB-001",
    "items::qty": "2"
  }
}
```

#### 💳 Pricing

This Actor uses Pay-Per-Event pricing. The charge is $0.00175 for each JSON record successfully converted into a CSV or TSV row. The total depends on the number of successfully converted rows.

#### 🔌 Integrations

Use `fileUrl` to retrieve the complete file and `datasetUrl` to read converted rows through Apify's API or Console. CSV and TSV files can then be opened in spreadsheet tools or used in another data workflow.

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

#### ❓ FAQ

##### Can I convert one JSON object as well as an array?

Yes. `jsonInput` accepts one object or an array of objects. A JSON URL can return either shape as well.

##### Can an array create more than one output row?

Yes. Set `arrayValueMode` to `rows` when array items should create rows. Use `cells` when they should stay together in one cell.

##### How are nested objects written to the file?

With `nestedValueMode` set to `flatten`, nested fields become path-based columns such as `customer.name`. With `preserve`, a nested value stays as JSON in one cell. `keySeparator` changes the text between path parts.

##### What happens when records have different fields?

The output uses one consistent column set. A missing or null value uses the text set in `nullValue`.

##### Can I limit how many source records are converted?

Yes. Set `maxRecords` to an integer source-record cap. Leave it empty to return all available results until the source is exhausted.

##### Can I use this as a JSON to Excel converter?

The Actor creates CSV or TSV, not an `.xlsx` workbook. You can open or import the resulting file in Excel.

##### Can I convert CSV back to JSON?

No. This Actor converts JSON into CSV or TSV. CSV-to-JSON conversion is outside its scope.

##### Can I use a JSON URL or an Apify dataset as the source?

Yes. Select `url` or `dataset` in `target`, then provide the URL or choose the dataset. For direct conversion, select `direct` and paste the JSON instead.

### 📝 Changelog

**0.0: Initial release**

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~json-to-csv-converter/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

- [XML JSON Converter](https://apify.com/maximedupre/xml-json-converter) — Convert XML to JSON or JSON to XML before moving structured data into a delimited file.
- [YAML Validator & Converter](https://apify.com/maximedupre/yaml-validator-converter) — Validate or convert JSON, YAML, and TOML documents before an export.
- [Schema Markup & JSON-LD Validator](https://apify.com/maximedupre/schema-markup-validator) — Check JSON-LD structured data on public pages before using it in a data workflow.
- [URL to BibTeX Converter](https://apify.com/maximedupre/url-to-bibtex-converter) — Turn citation URLs into structured rows for CSV or spreadsheet work.
- [JSON to CSV Converter — Flatten Nested Data](https://apify.com/junipr/json-to-csv-converter) — Handle nested JSON arrays when you need another CSV export path.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `target` (type: `string`):

Choose the source for the JSON records.

## `jsonInput` (type: `object,array`):

Paste one JSON object or an array of JSON objects. Example: {"name":"Ada"}.

## `jsonUrl` (type: `string`):

Enter one HTTP or HTTPS URL that returns one JSON object or an array of JSON objects.

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

Choose the Apify dataset that contains the JSON records to convert.

## `nestedValueMode` (type: `string`):

Choose whether nested objects become path-based columns or stay as JSON in one cell.

## `keySeparator` (type: `string`):

Choose the text between parts of a flattened key. This applies only when nested objects are flattened.

## `arrayValueMode` (type: `string`):

Choose whether array items create new rows or stay together in one cell.

## `includeFields` (type: `array`):

List the field names to export. Leave empty to include all fields.

## `excludeFields` (type: `array`):

List the field names to leave out of the export. Exclusion is applied after Include fields.

## `maxRecords` (type: `integer`):

Optionally stop after this many source records. Leave empty to return all available results until the source is exhausted.

## `outputFormat` (type: `string`):

Choose CSV or TSV for the output file.

## `columnDelimiter` (type: `string`):

Choose the text between columns. Use a comma for CSV or a tab for TSV.

## `includeHeaders` (type: `boolean`):

Add the column names as the first row.

## `nullValue` (type: `string`):

Choose the text to use for null or missing values.

## Actor input object example

```json
{
  "target": "direct",
  "jsonInput": [
    {
      "sku": "NB-001",
      "name": "A5 notebook",
      "price": 12.5,
      "inStock": true
    },
    {
      "sku": "PN-002",
      "name": "Blue pen set",
      "price": 6.75,
      "inStock": true
    }
  ],
  "nestedValueMode": "flatten",
  "keySeparator": ".",
  "arrayValueMode": "cells",
  "outputFormat": "csv",
  "columnDelimiter": ",",
  "includeHeaders": true,
  "nullValue": ""
}
```

# Actor output Schema

## `status` (type: `string`):

Shows whether the conversion finished.

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

Link to the complete CSV or TSV file in Apify storage.

## `fileFormat` (type: `string`):

Shows whether the file is CSV or TSV.

## `datasetUrl` (type: `string`):

Link to the converted rows in the default dataset.

## `rowCount` (type: `string`):

Number of converted output rows.

## `columnCount` (type: `string`):

Number of columns in the converted file.

## `columns` (type: `string`):

Names of the output columns in file order.

# 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 = {
    "target": "direct",
    "jsonInput": [
        {
            "sku": "NB-001",
            "name": "A5 notebook",
            "price": 12.5,
            "inStock": true
        },
        {
            "sku": "PN-002",
            "name": "Blue pen set",
            "price": 6.75,
            "inStock": true
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/json-to-csv-converter").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 = {
    "target": "direct",
    "jsonInput": [
        {
            "sku": "NB-001",
            "name": "A5 notebook",
            "price": 12.5,
            "inStock": True,
        },
        {
            "sku": "PN-002",
            "name": "Blue pen set",
            "price": 6.75,
            "inStock": True,
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/json-to-csv-converter").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 '{
  "target": "direct",
  "jsonInput": [
    {
      "sku": "NB-001",
      "name": "A5 notebook",
      "price": 12.5,
      "inStock": true
    },
    {
      "sku": "PN-002",
      "name": "Blue pen set",
      "price": 6.75,
      "inStock": true
    }
  ]
}' |
apify call maximedupre/json-to-csv-converter --silent --output-dataset

```

## MCP server setup

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

```

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/rUrNptuwdsi8wlosC/builds/52fPCpmAcFekVysph/openapi.json