read_export

Generated automatically from the published contract sources.

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.

A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/read_export, with a bearer credential and the action's payload as the JSON body. It also accepts GET.

Contract description

Read one export by its application and its id: the state (`running`, `completed`, `failed`), the outcome of a failed one, the progress counts, and, once it has ended, the manifest. The manifest names 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 answering another version than the manifest names is a file that moved after the listing. To download a completed export, call `mint_download_grant` and run the line it answers.

Access and action metadata

{
  "name": "read_export",
  "resource": "application",
  "tier": "observe",
  "summary": "Read one export by its application and its id: the state (`running`, `completed`, `failed`), the outcome of a failed one, the progress counts, and, once it has ended, the manifest. The manifest names 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 answering another version than the manifest names is a file that moved after the listing. To download a completed export, call `mint_download_grant` and run the line it answers.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

MCP catalog entry

{
  "name": "read_export",
  "tier": "observe",
  "scenario": "API-L0-18",
  "summary": "Read one export by its application and its id: the state (`running`, `completed`, `failed`), the outcome of a failed one, the progress counts, and, once it has ended, the manifest. The manifest names 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 answering another version than the manifest names is a file that moved after the listing. To download a completed export, call `mint_download_grant` and run the line it answers.",
  "owners": [
    "API-L0-18",
    "API-L0-23",
    "MAPI-21"
  ]
}

request

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["application","export"]
/properties/application The id of the application the export reads.

Type: string
/properties/export The export's id, from `request_export`; an id the application does not hold refuses 404 `not_found`.

Type: string

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 this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting 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 stands.

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`. The line `mint_download_grant` answers downloads 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 stands 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 answering 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",
      "export"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The id of the application the export reads."
      },
      "export": {
        "type": "string",
        "description": "The export's id, from `request_export`; an id the application does not hold refuses 404 `not_found`."
      }
    }
  },
  "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 this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting 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 stands."
          },
          "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`. The line `mint_download_grant` answers downloads 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 stands 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 answering another version (its ETag) is a file that moved after the listing."
                          },
                          "last_written_at": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "detail": {
        "type": "string"
      }
    }
  }
}

Shared contracts