---
title: "read_export"
description: "Generated reference for the management action read_export: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-export
order: 90
visibility: public
redirects_from: []
---

# read\_export

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/read_export`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `tzcloud_read_export`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Read your application's export state, outcome and progress\. Pass `application` and `export`, or omit `export` for the latest\. Download a completed export with `request_export` and `download: true`, then run its command\. A completed export with `manifest` null needs a new export\. On `interrupted`, request a fresh export for the same application and environment\. On `table_bound_exceeded`, page the table with `query_database` instead\. For another repeating failure, use `submit_feedback` with its reference\.

## More about this action

Give the export id from `request_export` to read one export\. Leave `export` out for the application's newest export in `environment`, production if omitted, whether running or ended\. The request instant orders exports, with the export id breaking a tie\. With an id, `environment` is ignored\. Both forms give the same answer, including the export's id\. If none is held, the read refuses `not_found`\.

The state is `running`, `completed` or `failed`\. The manifest lists table CSVs, columns, row counts, one database `read_at`, and area files with sizes and version tags\. A changed downloaded version means the file moved after listing\. On `completed` with `manifest` null, the files were replaced or deleted\.

`interrupted` marks a stopped `failed` export, for example after a plane restart or stale heartbeat\. Request a fresh export for the same application and environment\. On `table_bound_exceeded`, the manifest lists the table and bound\. Page that table with `query_database` instead of exporting again\. For another repeating failure, use `submit_feedback` with its reference\.

## Access and action metadata

```json
{
  "name": "read_export",
  "resource": "application",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Read an application's export by id, or its latest in `environment` (production by default) without an id. It gives the state (`running`, `completed`, `failed`), the outcome of a failed one, the progress counts, and, once it has ended, the manifest. The manifest lists each table's CSV file with its columns and row count and the database's read instant, and each area file with its size and version tag. A download that returns a different version from the manifest's is a file that moved after the listing. Once an export has completed, you download it by calling `request_export` with `download: true` and running the command it returns.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_export",
  "title": "Read data export",
  "tier": "observe",
  "scenario": "API-L0-18",
  "summary": "Read your application's export state, outcome and progress. Pass `application` and `export`, or omit `export` for the latest. Download a completed export with `request_export` and `download: true`, then run its command. A completed export with `manifest` null needs a new export. On `interrupted`, request a fresh export for the same application and environment. On `table_bound_exceeded`, page the table with `query_database` instead. For another repeating failure, use `submit_feedback` with its reference.",
  "owners": [
    "API-L0-18",
    "API-L0-23",
    "MAPI-21"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application"\] |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>export | The export's id from `request_export`; omit it to read the application's newest export for `environment`\. An id the application does not hold refuses 404 `not_found`\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | Chooses the latest export when `export` is omitted; production by default\. Ignored when `export` is given, which carries its own environment\.<br><br>Type: string<br>Allowed values: \["development","production"\] |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","export","application","environment","state","outcome","requested\_at","heartbeat\_at","ended\_at","progress","area","manifest\_file","manifest"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>export | Type: string |
| /<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>environment | Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>state | Type: string<br>Allowed values: \["running","completed","failed"\] |
| /<wbr>properties/<wbr>outcome | null while running and on a completed export; on a failed one `interrupted` \(a restart, or a heartbeat older than the stale bound\), `table_bound_exceeded`, `database_failed`, `files_failed`, `area_unavailable`, or `runner_failed`\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>requested\_at | Type: string |
| /<wbr>properties/<wbr>heartbeat\_at | The instant the pass last reported; a running export whose heartbeat is older than the stale bound reads `failed` `interrupted`\.<br><br>Type: string |
| /<wbr>properties/<wbr>ended\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>progress | Type: object<br>Required fields: \["tables\_total","tables\_written","bytes\_written","areas\_listed","files\_listed","database\_read\_at","files\_read\_at"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>progress/<wbr>properties/<wbr>tables\_total | The tables the database holds, null until the pass has read the catalog; 0 where no database exists\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>progress/<wbr>properties/<wbr>tables\_written | Type: integer |
| /<wbr>properties/<wbr>progress/<wbr>properties/<wbr>bytes\_written | Type: integer |
| /<wbr>properties/<wbr>progress/<wbr>properties/<wbr>areas\_listed | Type: integer |
| /<wbr>properties/<wbr>progress/<wbr>properties/<wbr>files\_listed | Type: integer |
| /<wbr>properties/<wbr>progress/<wbr>properties/<wbr>database\_read\_at | The database member's snapshot instant\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>progress/<wbr>properties/<wbr>files\_read\_at | The instant the files member's listing began\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>area | The export area, `export-<application id>`\.<br><br>Type: string |
| /<wbr>properties/<wbr>manifest\_file | The manifest's name in the export area, `<export id>/manifest.json`\. Run the line `request_export` with `download: true` returns to download it with the export's other files\.<br><br>Type: string |
| /<wbr>properties/<wbr>manifest | null while running, and where the manifest file is gone from the export area\. Otherwise the manifest the pass wrote\.<br><br>Type: \["object","null"\]<br>Required fields: \["export","application","environment","area","requested\_at","ended\_at","state","outcome","failure","database","files"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>export | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>environment | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>area | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>requested\_at | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>ended\_at | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>state | Type: string<br>Allowed values: \["completed","failed"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>outcome | Type: \["string","null"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>failure | On a failed export, the member that failed \(`database`, `files`, `area`, or `pass`\), and for a table past the per\-table bound, the table and the bound in bytes\.<br><br>Type: \["object","null"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>failure/<wbr>properties/<wbr>member | Type: string<br>Allowed values: \["database","files","area","pass"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>failure/<wbr>properties/<wbr>table | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>failure/<wbr>properties/<wbr>bound | Type: integer |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database | Type: object<br>Required fields: \["state","read\_at","isolation","tables"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>state | `absent` where no database exists for the environment\.<br><br>Type: string<br>Allowed values: \["written","absent","failed","not\_read"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>read\_at | The snapshot instant every table was read at\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>isolation | Required value: repeatable read |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables | Type: array |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items | Type: object<br>Required fields: \["table","file","columns","rows","bytes","version"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items/<wbr>properties/<wbr>table | The table's name, `schema.table` outside the public schema\.<br><br>Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items/<wbr>properties/<wbr>file | The CSV file's name in the export area, `<export id>/database/<table>.csv`\.<br><br>Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items/<wbr>properties/<wbr>columns | Type: array |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items/<wbr>properties/<wbr>columns/<wbr>items | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items/<wbr>properties/<wbr>rows | Type: integer |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items/<wbr>properties/<wbr>bytes | Type: integer |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>database/<wbr>properties/<wbr>tables/<wbr>items/<wbr>properties/<wbr>version | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files | Type: object<br>Required fields: \["state","read\_at","read\_until","areas"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>state | Type: string<br>Allowed values: \["listed","failed","not\_read"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>read\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>read\_until | Type: \["string","null"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas | Type: array |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items | Type: object<br>Required fields: \["area","read\_at","read\_until","files"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>area | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>read\_at | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>read\_until | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>files | Type: array |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>files/<wbr>items | Type: object<br>Required fields: \["name","size","content\_type","version","last\_written\_at"\] |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>name | The file's name in its own area, downloaded with the environment's header\.<br><br>Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>size | Type: integer |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>content\_type | Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>version | The version the listing read; a download returning another version \(its ETag\) is a file that moved after the listing\.<br><br>Type: string |
| /<wbr>properties/<wbr>manifest/<wbr>properties/<wbr>files/<wbr>properties/<wbr>areas/<wbr>items/<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>last\_written\_at | Type: string |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "export": {
        "type": "string",
        "description": "The export's id from `request_export`; omit it to read the application's newest export for `environment`. An id the application does not hold refuses 404 `not_found`."
      },
      "environment": {
        "type": "string",
        "enum": [
          "development",
          "production"
        ],
        "description": "Chooses the latest export when `export` is omitted; production by default. Ignored when `export` is given, which carries its own environment."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "export",
      "application",
      "environment",
      "state",
      "outcome",
      "requested_at",
      "heartbeat_at",
      "ended_at",
      "progress",
      "area",
      "manifest_file",
      "manifest"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "export": {
        "type": "string"
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "enum": [
          "development",
          "production"
        ]
      },
      "state": {
        "type": "string",
        "enum": [
          "running",
          "completed",
          "failed"
        ]
      },
      "outcome": {
        "type": [
          "string",
          "null"
        ],
        "description": "null while running and on a completed export; on a failed one `interrupted` (a restart, or a heartbeat older than the stale bound), `table_bound_exceeded`, `database_failed`, `files_failed`, `area_unavailable`, or `runner_failed`."
      },
      "requested_at": {
        "type": "string"
      },
      "heartbeat_at": {
        "type": "string",
        "description": "The instant the pass last reported; a running export whose heartbeat is older than the stale bound reads `failed` `interrupted`."
      },
      "ended_at": {
        "type": [
          "string",
          "null"
        ]
      },
      "progress": {
        "type": "object",
        "required": [
          "tables_total",
          "tables_written",
          "bytes_written",
          "areas_listed",
          "files_listed",
          "database_read_at",
          "files_read_at"
        ],
        "properties": {
          "tables_total": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The tables the database holds, null until the pass has read the catalog; 0 where no database exists."
          },
          "tables_written": {
            "type": "integer"
          },
          "bytes_written": {
            "type": "integer"
          },
          "areas_listed": {
            "type": "integer"
          },
          "files_listed": {
            "type": "integer"
          },
          "database_read_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "The database member's snapshot instant."
          },
          "files_read_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "The instant the files member's listing began."
          }
        },
        "additionalProperties": false
      },
      "area": {
        "type": "string",
        "description": "The export area, `export-<application id>`."
      },
      "manifest_file": {
        "type": "string",
        "description": "The manifest's name in the export area, `<export id>/manifest.json`. Run the line `request_export` with `download: true` returns to download it with the export's other files."
      },
      "manifest": {
        "type": [
          "object",
          "null"
        ],
        "description": "null while running, and where the manifest file is gone from the export area. Otherwise the manifest the pass wrote.",
        "required": [
          "export",
          "application",
          "environment",
          "area",
          "requested_at",
          "ended_at",
          "state",
          "outcome",
          "failure",
          "database",
          "files"
        ],
        "properties": {
          "export": {
            "type": "string"
          },
          "application": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "area": {
            "type": "string"
          },
          "requested_at": {
            "type": "string"
          },
          "ended_at": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "completed",
              "failed"
            ]
          },
          "outcome": {
            "type": [
              "string",
              "null"
            ]
          },
          "failure": {
            "type": [
              "object",
              "null"
            ],
            "description": "On a failed export, the member that failed (`database`, `files`, `area`, or `pass`), and for a table past the per-table bound, the table and the bound in bytes.",
            "properties": {
              "member": {
                "type": "string",
                "enum": [
                  "database",
                  "files",
                  "area",
                  "pass"
                ]
              },
              "table": {
                "type": "string"
              },
              "bound": {
                "type": "integer"
              }
            }
          },
          "database": {
            "type": "object",
            "required": [
              "state",
              "read_at",
              "isolation",
              "tables"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "written",
                  "absent",
                  "failed",
                  "not_read"
                ],
                "description": "`absent` where no database exists for the environment."
              },
              "read_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The snapshot instant every table was read at."
              },
              "isolation": {
                "const": "repeatable read"
              },
              "tables": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "table",
                    "file",
                    "columns",
                    "rows",
                    "bytes",
                    "version"
                  ],
                  "properties": {
                    "table": {
                      "type": "string",
                      "description": "The table's name, `schema.table` outside the public schema."
                    },
                    "file": {
                      "type": "string",
                      "description": "The CSV file's name in the export area, `<export id>/database/<table>.csv`."
                    },
                    "columns": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "rows": {
                      "type": "integer"
                    },
                    "bytes": {
                      "type": "integer"
                    },
                    "version": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "files": {
            "type": "object",
            "required": [
              "state",
              "read_at",
              "read_until",
              "areas"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "listed",
                  "failed",
                  "not_read"
                ]
              },
              "read_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "read_until": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "areas": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "area",
                    "read_at",
                    "read_until",
                    "files"
                  ],
                  "properties": {
                    "area": {
                      "type": "string"
                    },
                    "read_at": {
                      "type": "string"
                    },
                    "read_until": {
                      "type": "string"
                    },
                    "files": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "size",
                          "content_type",
                          "version",
                          "last_written_at"
                        ],
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "The file's name in its own area, downloaded with the environment's header."
                          },
                          "size": {
                            "type": "integer"
                          },
                          "content_type": {
                            "type": "string"
                          },
                          "version": {
                            "type": "string",
                            "description": "The version the listing read; a download returning another version (its ETag) is a file that moved after the listing."
                          },
                          "last_written_at": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "detail": {
        "type": "string"
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
