# Convert TSV to JSON

> To convert TSV to JSON, send one POST to /v1/csv-to-json with the TSV source. Each call costs $0.005 in USDC on Base via x402, with no account and no API key. The source file can be up to 25 MB.

- Endpoint: `POST /v1/csv-to-json`
- Price: $0.005 per successful call
- API: [csv-to-json](https://grist.tools/docs/csv-to-json)

## Limits

| Limit | Value |
| --- | --- |
| Largest source file | 25 MB (26,214,400 bytes) |
| Timeout | 30 s |
| Source formats | CSV, TSV |
| Output formats | JSON |
| Option header | default true |
| Option max_rows | default 10000 |

## Example

A real TSV to JSON run of csv-to-json.

Request body:

```json
{
  "url": "https://grist.tools/samples/documents/garden-plots.tsv",
  "header": true
}
```

Response:

```json
{
  "source_url": "https://grist.tools/samples/documents/garden-plots.tsv",
  "delimiter": "\t",
  "columns": [
    "plot",
    "holder",
    "crop",
    "area_m2",
    "notes"
  ],
  "rows": [
    {
      "plot": "A1",
      "holder": "Maple Group",
      "crop": "tomatoes",
      "area_m2": "12",
      "notes": "Stakes needed, north side"
    },
    {
      "plot": "A2",
      "holder": "Oak Group",
      "crop": "beans",
      "area_m2": "08",
      "notes": ""
    },
    {
      "plot": "B1",
      "holder": "Willow Group",
      "crop": "herbs, mixed",
      "area_m2": "6",
      "notes": "Shares water with \"B2\""
    },
    {
      "plot": "B2",
      "holder": "Birch Group",
      "crop": "squash",
      "area_m2": "10.50",
      "notes": "Compost added in April"
    }
  ],
  "row_count": 4,
  "truncated": false
}
```

Source file: documents/garden-plots.tsv, 212 bytes. Tab-separated table of four community garden plots with a header row (plot, holder, crop, area_m2, notes), the same data as garden-plots.csv including an empty field, a comma inside a value and embedded double quotes. The request sets header to true. The recorded run returned 396 bytes of JSON, 1.9 times the source size, with 4 rows and 5 columns.

## Format notes

TSV as a source: TSV separates values with tab characters, so a comma inside a value is ordinary text and needs no quoting on its account. Grist reads TSV through csv-to-json, where tab is among the delimiters detected automatically from the opening rows, or it can be named explicitly. The input passes the same gate as CSV: strict UTF-8, no NUL bytes, and only UTF-8 charset declarations. Values stay strings, headings are normalised the same way, and the response reports a tab as the delimiter it used. Quoted fields still follow the parser's quoting rules, so a double quote inside a TSV value is read through the same quote handling as in CSV. TSV has an input role only: no service in the catalogue lists it as an output format, so it appears on these pages as a source.

JSON as a target: The JSON that Grist returns keeps different value types depending on the reader. csv-to-json leaves every cell a string and returns header-keyed objects, or positional arrays when header is false, together with the delimiter, the column list, a row count and a truncated flag. xlsx-to-json keeps numbers and booleans as typed values, turns dates into ISO-8601 strings, uses the cached result of a formula, and reduces rich text and hyperlinks to their text; error cells become null. It returns every worksheet, or a single sheet selected by exact name. A delimited source therefore produces JSON that needs type conversion by the caller, while a workbook source produces typed values straight away. Blank and duplicate headings are made unique by both readers before they become object keys.

## Errors

- `invalid_input` (400)
- `blocked_target` (403)
- `unreachable_target` (424)
- `upstream_timeout` (424)
- `unsupported_content_type` (415)
- `too_large` (413)
- `unprocessable` (422)
- `internal` (500)

When each is raised, and what it means for payment: https://grist.tools/docs/csv-to-json.

## Questions

### What does it cost to convert TSV to JSON?

$0.005 per call, paid in USDC on Base via x402.

### How large can the TSV file be?

Up to 25 MB (26,214,400 bytes). Past a limit the call answers too_large (413).

### What happens if the conversion fails?

The tool answers with a typed JSON error from the errors table. Payment is settled only after the tool has produced its result; a call that fails inside the tool is never settled.

This page as HTML: https://grist.tools/tools/tsv-to-json. Every page of grist.tools has a Markdown version at its address plus .md.
