read_export #
On this page
Generated automatically from the published 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).
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 #
{
"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 #
{
"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 Required fields: ["application"] |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
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.Type: string |
| / |
Chooses the latest export when export is omitted; production by default. Ignored when export is given, which carries its own environment.Type: string Allowed values: ["development","production"] |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","export","application","environment","state","outcome","requested_at","heartbeat_at","ended_at","progress","area","manifest_file","manifest"] |
| / |
Required value: 1 |
| / |
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. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string Allowed values: ["development","production"] |
| / |
Type: string Allowed values: ["running","completed","failed"] |
| / |
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.Type: ["string","null"] |
| / |
Type: string |
| / |
The instant the pass last reported; a running export whose heartbeat is older than the stale bound reads failed interrupted.Type: string |
| / |
Type: ["string","null"] |
| / |
Type: object Required fields: ["tables_total","tables_written","bytes_written","areas_listed","files_listed","database_read_at","files_read_at"] Additional properties: false |
| / |
The tables the database holds, null until the pass has read the catalog; 0 where no database exists. Type: ["integer","null"] |
| / |
Type: integer |
| / |
Type: integer |
| / |
Type: integer |
| / |
Type: integer |
| / |
The database member's snapshot instant. Type: ["string","null"] |
| / |
The instant the files member's listing began. Type: ["string","null"] |
| / |
The export area, export-<application id>.Type: string |
| / |
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.Type: string |
| / |
null while running, and where the manifest file is gone from the export area. Otherwise the manifest the pass wrote. Type: ["object","null"] Required fields: ["export","application","environment","area","requested_at","ended_at","state","outcome","failure","database","files"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string Allowed values: ["completed","failed"] |
| / |
Type: ["string","null"] |
| / |
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.Type: ["object","null"] |
| / |
Type: string Allowed values: ["database","files","area","pass"] |
| / |
Type: string |
| / |
Type: integer |
| / |
Type: object Required fields: ["state","read_at","isolation","tables"] |
| / |
absent where no database exists for the environment.Type: string Allowed values: ["written","absent","failed","not_read"] |
| / |
The snapshot instant every table was read at. Type: ["string","null"] |
| / |
Required value: repeatable read |
| / |
Type: array |
| / |
Type: object Required fields: ["table","file","columns","rows","bytes","version"] |
| / |
The table's name, schema.table outside the public schema.Type: string |
| / |
The CSV file's name in the export area, <export id>/database/<table>.csv.Type: string |
| / |
Type: array |
| / |
Type: string |
| / |
Type: integer |
| / |
Type: integer |
| / |
Type: string |
| / |
Type: object Required fields: ["state","read_at","read_until","areas"] |
| / |
Type: string Allowed values: ["listed","failed","not_read"] |
| / |
Type: ["string","null"] |
| / |
Type: ["string","null"] |
| / |
Type: array |
| / |
Type: object Required fields: ["area","read_at","read_until","files"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: array |
| / |
Type: object Required fields: ["name","size","content_type","version","last_written_at"] |
| / |
The file's name in its own area, downloaded with the environment's header. Type: string |
| / |
Type: integer |
| / |
Type: string |
| / |
The version the listing read; a download returning another version (its ETag) is a file that moved after the listing. Type: string |
| / |
Type: string |
| / |
Type: string |
Complete payload contract #
{
"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: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md