read_export #

View this page as Markdown

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"]
/properties/application Your account's application id from list_applications, not its name or label.

Type: string
/properties/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.

Type: string
/properties/environment 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"]
/properties/contract_version Required value: 1
/properties/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.

Type: string
Pattern: ^[0-9a-f]{10}$
/properties/export Type: string
/properties/application Type: string
/properties/environment Type: string
Allowed values: ["development","production"]
/properties/state Type: string
Allowed values: ["running","completed","failed"]
/properties/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.

Type: ["string","null"]
/properties/requested_at Type: string
/properties/heartbeat_at The instant the pass last reported; a running export whose heartbeat is older than the stale bound reads failed interrupted.

Type: string
/properties/ended_at Type: ["string","null"]
/properties/progress Type: object
Required fields: ["tables_total","tables_written","bytes_written","areas_listed","files_listed","database_read_at","files_read_at"]
Additional properties: false
/properties/progress/properties/tables_total The tables the database holds, null until the pass has read the catalog; 0 where no database exists.

Type: ["integer","null"]
/properties/progress/properties/tables_written Type: integer
/properties/progress/properties/bytes_written Type: integer
/properties/progress/properties/areas_listed Type: integer
/properties/progress/properties/files_listed Type: integer
/properties/progress/properties/database_read_at The database member's snapshot instant.

Type: ["string","null"]
/properties/progress/properties/files_read_at The instant the files member's listing began.

Type: ["string","null"]
/properties/area The export area, export-<application id>.

Type: string
/properties/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.

Type: string
/properties/manifest 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"]
/properties/manifest/properties/export Type: string
/properties/manifest/properties/application Type: string
/properties/manifest/properties/environment Type: string
/properties/manifest/properties/area Type: string
/properties/manifest/properties/requested_at Type: string
/properties/manifest/properties/ended_at Type: string
/properties/manifest/properties/state Type: string
Allowed values: ["completed","failed"]
/properties/manifest/properties/outcome Type: ["string","null"]
/properties/manifest/properties/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.

Type: ["object","null"]
/properties/manifest/properties/failure/properties/member Type: string
Allowed values: ["database","files","area","pass"]
/properties/manifest/properties/failure/properties/table Type: string
/properties/manifest/properties/failure/properties/bound Type: integer
/properties/manifest/properties/database Type: object
Required fields: ["state","read_at","isolation","tables"]
/properties/manifest/properties/database/properties/state absent where no database exists for the environment.

Type: string
Allowed values: ["written","absent","failed","not_read"]
/properties/manifest/properties/database/properties/read_at The snapshot instant every table was read at.

Type: ["string","null"]
/properties/manifest/properties/database/properties/isolation Required value: repeatable read
/properties/manifest/properties/database/properties/tables Type: array
/properties/manifest/properties/database/properties/tables/items Type: object
Required fields: ["table","file","columns","rows","bytes","version"]
/properties/manifest/properties/database/properties/tables/items/properties/table The table's name, schema.table outside the public schema.

Type: string
/properties/manifest/properties/database/properties/tables/items/properties/file The CSV file's name in the export area, <export id>/database/<table>.csv.

Type: string
/properties/manifest/properties/database/properties/tables/items/properties/columns Type: array
/properties/manifest/properties/database/properties/tables/items/properties/columns/items Type: string
/properties/manifest/properties/database/properties/tables/items/properties/rows Type: integer
/properties/manifest/properties/database/properties/tables/items/properties/bytes Type: integer
/properties/manifest/properties/database/properties/tables/items/properties/version Type: string
/properties/manifest/properties/files Type: object
Required fields: ["state","read_at","read_until","areas"]
/properties/manifest/properties/files/properties/state Type: string
Allowed values: ["listed","failed","not_read"]
/properties/manifest/properties/files/properties/read_at Type: ["string","null"]
/properties/manifest/properties/files/properties/read_until Type: ["string","null"]
/properties/manifest/properties/files/properties/areas Type: array
/properties/manifest/properties/files/properties/areas/items Type: object
Required fields: ["area","read_at","read_until","files"]
/properties/manifest/properties/files/properties/areas/items/properties/area Type: string
/properties/manifest/properties/files/properties/areas/items/properties/read_at Type: string
/properties/manifest/properties/files/properties/areas/items/properties/read_until Type: string
/properties/manifest/properties/files/properties/areas/items/properties/files Type: array
/properties/manifest/properties/files/properties/areas/items/properties/files/items Type: object
Required fields: ["name","size","content_type","version","last_written_at"]
/properties/manifest/properties/files/properties/areas/items/properties/files/items/properties/name The file's name in its own area, downloaded with the environment's header.

Type: string
/properties/manifest/properties/files/properties/areas/items/properties/files/items/properties/size Type: integer
/properties/manifest/properties/files/properties/areas/items/properties/files/items/properties/content_type Type: string
/properties/manifest/properties/files/properties/areas/items/properties/files/items/properties/version The version the listing read; a download returning another version (its ETag) is a file that moved after the listing.

Type: string
/properties/manifest/properties/files/properties/areas/items/properties/files/items/properties/last_written_at Type: string
/properties/detail 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 #