DataExportResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cogram-com/json-schema/cogram-com-data-export-response-schema.json",
  "title": "DataExportResponse",
  "description": "Full read shape returned by ``GET /data_exports`` and ``GET /data_exports/{id}``.\n\n``parts`` is empty until the data_export reaches ``COMPLETED``. Even after\n``EXPIRED``, the row remains as an audit record — clients distinguish\n\"downloadable\" from \"audit-only\" via the ``status`` field.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/api.cogram.com-v1-openapi.json#/components/schemas/DataExportResponse",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id"
    },
    "organization_id": {
      "type": "string",
      "title": "Organization Id"
    },
    "source": {
      "type": "string",
      "enum": [
        "ui",
        "api"
      ],
      "title": "Source"
    },
    "requester_user_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Requester User Id",
      "description": "`ui` source only."
    },
    "requester_api_key_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Requester Api Key Id",
      "description": "`api` source only."
    },
    "requester_api_key_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Requester Api Key Name",
      "description": "`api` source only. Prefer this over parsing `requester_display`."
    },
    "requester_forwarded_user": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Requester Forwarded User",
      "description": "`X-Forwarded-User` header value at create time."
    },
    "requester_display": {
      "type": "string",
      "title": "Requester Display",
      "description": "Human-readable attribution: the user's name (their email if the name is empty), `API key '<name>'`, or `<forwarded_user> (via API key '<name>')`. Degrades to `<forwarded_user> (via deleted API key)` or `unknown` when the linked user or key row was deleted after the export was created."
    },
    "project_ids": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Project Ids",
      "description": "Scope as requested — empty for org-wide exports. Retains ids of projects deleted after the export was created, so `projects` may be shorter."
    },
    "projects": {
      "items": {
        "$ref": "#/$defs/DataExportProjectRef"
      },
      "type": "array",
      "title": "Projects",
      "description": "Scope projects that still exist, in `project_ids` order."
    },
    "project_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Project Id",
      "description": "Set only for single-project exports; null otherwise.",
      "deprecated": true
    },
    "project_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Project Name",
      "description": "Set only when `project_id` is set.",
      "deprecated": true
    },
    "project_customer_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Project Customer Id",
      "description": "Customer's own project label. Not unique — use `project_id` for identity.",
      "deprecated": true
    },
    "time_filter": {
      "$ref": "#/$defs/TimeFilter",
      "description": "Echo of the request."
    },
    "document_formats": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Document Formats",
      "description": "Echo of the request. Typed loosely so a row written by a newer deployment, carrying a format this one does not know, still serializes instead of failing the whole listing."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "cancelling",
        "cancelled",
        "completed",
        "failed",
        "expired"
      ],
      "title": "Status"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error",
      "description": "Set when `status` is `failed`."
    },
    "requested_at": {
      "type": "string",
      "format": "date-time",
      "title": "Requested At"
    },
    "started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Started At"
    },
    "completed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Completed At",
      "description": "Also set on failure and cancellation."
    },
    "expires_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Expires At",
      "description": "Parts are deleted at this time, 7 days after completion."
    },
    "parts": {
      "items": {
        "$ref": "#/$defs/DataExportPartResponse"
      },
      "type": "array",
      "title": "Parts",
      "description": "Zip parts with signed URLs. Empty until `status` is `completed`."
    }
  },
  "type": "object",
  "required": [
    "id",
    "organization_id",
    "source",
    "requester_user_id",
    "requester_api_key_id",
    "requester_api_key_name",
    "requester_forwarded_user",
    "requester_display",
    "project_ids",
    "project_id",
    "time_filter",
    "document_formats",
    "status",
    "error",
    "requested_at",
    "started_at",
    "completed_at",
    "expires_at"
  ],
  "$defs": {
    "AllTimeFilter": {
      "properties": {
        "mode": {
          "type": "string",
          "const": "all_time",
          "title": "Mode",
          "default": "all_time"
        }
      },
      "type": "object",
      "title": "AllTimeFilter",
      "description": "All available data, no time bound. Only valid for project-scoped\ndata_exports (one or more ``project_ids``)."
    },
    "DataExportPartResponse": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id"
        },
        "part_index": {
          "type": "integer",
          "title": "Part Index",
          "description": "Zero-indexed."
        },
        "size_bytes": {
          "type": "integer",
          "title": "Size Bytes",
          "description": "Compressed size."
        },
        "signed_url": {
          "type": "string",
          "title": "Signed Url",
          "description": "Pre-signed, valid 1 hour. Re-fetch on each read, never cache."
        }
      },
      "type": "object",
      "required": [
        "id",
        "part_index",
        "size_bytes",
        "signed_url"
      ],
      "title": "DataExportPartResponse",
      "description": "One zip part within a completed data_export, with a freshly-signed download URL.\n\n``signed_url`` is regenerated by the service on every status read (signing\nis local math, no S3 round-trip) — clients should never cache it past the\n1-hour validity window stamped on the URL itself."
    },
    "DataExportProjectRef": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id"
        },
        "name": {
          "type": "string",
          "title": "Name"
        },
        "customer_project_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Customer Project Id",
          "description": "Customer's own project label. Not unique — use `id` for identity."
        }
      },
      "type": "object",
      "required": [
        "id",
        "name",
        "customer_project_id"
      ],
      "title": "DataExportProjectRef",
      "description": "One project in a data_export's scope, with the labels a human needs to\nrecognize it. Only projects that still exist are represented — see\n``DataExportResponse.project_ids`` for the scope as requested."
    },
    "TimeFilter": {
      "oneOf": [
        {
          "$ref": "#/$defs/TimeRangeFilter"
        },
        {
          "$ref": "#/$defs/AllTimeFilter"
        }
      ],
      "title": "TimeFilter",
      "description": "Discriminated-union wrapper so the JSONB column can use ``PydanticJsonbType``.\n\nStored shape mirrors ``root`` directly (``RootModel`` serializes without\na wrapping field), e.g. ``{\"mode\": \"range\", \"start\": ..., \"end\": ...}``."
    },
    "TimeRangeFilter": {
      "properties": {
        "mode": {
          "type": "string",
          "const": "range",
          "title": "Mode",
          "default": "range"
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "title": "Start",
          "description": "Inclusive. Must be timezone-aware."
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "title": "End",
          "description": "Inclusive. Must be timezone-aware."
        }
      },
      "type": "object",
      "required": [
        "start",
        "end"
      ],
      "title": "TimeRangeFilter",
      "description": "Closed time range. Both bounds timezone-aware; ``end`` must be >= ``start``."
    }
  }
}