> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olira.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create export

> Starts an async batch export that compiles selected patients into a zip of typed Parquets (logs, state_modules, view_blocks, events, extracted).

<CodeGroup>
  ```python Python theme={null}
  olira.create_export(
      start: str | datetime,
      end: str | datetime,
      include: ExportInclude | dict,
      patient_ids: list[str] | None = None,
      cohort_id: str | None = None,
      scope: Literal["project"] | None = None,
  ) -> ExportJob
  ```

  ```csharp C# theme={null}
  OliraModule.CreateExport(
      DateTimeOffset start,
      DateTimeOffset end,
      ExportInclude include,
      IReadOnlyList<string>? patientIds = null,
      string? cohortId = null,
      string? scope = null,
  )  // -> ExportJob
  ```
</CodeGroup>

**Requires scope:** `sdk:state-read`

Provide exactly one of patient\_ids, cohort\_id, or scope="project". Poll get\_export until downloadable, then download\_export for a presigned URL.

## Parameters

<ParamField body="start" type="str | datetime" required>
  Inclusive window start (UTC). Versions overlapping \[start, end] are selected.
</ParamField>

<ParamField body="end" type="str | datetime" required>
  Inclusive window end (UTC).
</ParamField>

<ParamField body="include" type="ExportInclude | dict" required>
  Content selection. Each of logs, state\_modules, view\_blocks, events, extracted may be true/false or a filter object.
</ParamField>

<ParamField body="patient_ids" type="list[str] | None">
  Explicit patient ids (max 500). Mutually exclusive with cohort\_id and scope.
</ParamField>

<ParamField body="cohort_id" type="str | None">
  Cohort whose membership is exported. Mutually exclusive with patient\_ids and scope.
</ParamField>

<ParamField body="scope" type="Literal[&#x22;project&#x22;] | None">
  Use "project" to export every non-deleted patient in the resolved project.
</ParamField>

## Returns

`ExportJob` — Job snapshot including export\_id, status, stage, and progress.

<ResponseField name="export_id" type="str">
  Export job identifier for polling and download.
</ResponseField>

<ResponseField name="status" type="str">
  queued | running | completed | completed\_with\_errors | failed | cancelled.
</ResponseField>

<ResponseField name="stage" type="str | None">
  Pipeline stage (planning, exporting, finalizing, …).
</ResponseField>

<ResponseField name="progress_pct" type="float">
  0–100 progress estimate.
</ResponseField>

<ResponseField name="selection" type="str | None">
  patient\_ids | cohort | project.
</ResponseField>

<ResponseField name="patient_count" type="int">
  Number of patients in the export.
</ResponseField>

<ResponseField name="downloadable" type="bool">
  True when download\_export can return a URL.
</ResponseField>

## Raises

| Exception         | When                                                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ValidationError` | Missing/invalid selection (must provide exactly one of patient\_ids, cohort\_id, scope), bad window, or empty include. |
| `AuthError`       | HTTP 401 or 403 — invalid API key or insufficient OAuth scope for this endpoint.                                       |
| `ServerError`     | HTTP 409 (e.g. conflicting external identifier) or repeated 5xx after retries; includes status\_code when applicable.  |
| `RateLimitError`  | HTTP 429 — rate limited; check retry\_after (seconds).                                                                 |
| `NetworkError`    | Connection timeout, DNS failure, or read error after retries.                                                          |

<RequestExample>
  ```python Python theme={null}
  import olira
  from datetime import datetime, timedelta, timezone
  from olira import ExportInclude

  olira.init(api_key="YOUR_API_KEY")
  end = datetime.now(tz=timezone.utc)
  start = end - timedelta(days=30)
  job = olira.create_export(
      start=start,
      end=end,
      include=ExportInclude(
          logs=True,
          state_modules=True,
          view_blocks=True,
          events=True,
          extracted=True,
      ),
      patient_ids=["8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82"],
  )
  print(job.export_id, job.status)
  ```

  ```csharp C# theme={null}
  using Olira;

  OliraModule.Init(apiKey: "YOUR_API_KEY");
  var job = OliraModule.CreateExport(
      start: DateTimeOffset.UtcNow.AddDays(-30),
      end: DateTimeOffset.UtcNow,
      include: new ExportInclude
      {
          Logs = true,
          StateModules = true,
          ViewBlocks = true,
          Events = true,
          Extracted = true,
      },
      patientIds: ["8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82"]);
  Console.WriteLine($"{job.ExportId} {job.Status}");
  ```

  ```http HTTP theme={null}
  POST /v1/exports
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "start": "2026-07-11T00:00:00Z",
    "end": "2026-08-10T00:00:00Z",
    "patient_ids": ["8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82"],
    "include": {
      "logs": true,
      "state_modules": true,
      "view_blocks": true,
      "events": true,
      "extracted": true
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```python 200 theme={null}
  ExportJob(
      export_id="exp-job-001",
      status="queued",
      stage="queued",
      progress_pct=0.0,
      selection="patient_ids",
      patient_count=1,
      downloadable=False,
  )
  ```

  ```json 401 theme={null}
  {
    "error": true,
    "status_code": 401,
    "error_type": "authentication_error",
    "message": "Could not validate credentials",
    "details": [
      {
        "type": "authentication_error",
        "message": "Could not validate credentials"
      }
    ],
    "timestamp": "2026-05-06T12:00:00+00:00"
  }
  ```

  ```json 403 theme={null}
  {
    "error": true,
    "status_code": 403,
    "error_type": "authorization_error",
    "message": "Insufficient OAuth scope for this endpoint",
    "details": [
      {
        "type": "authorization_error",
        "message": "Insufficient OAuth scope for this endpoint"
      }
    ],
    "timestamp": "2026-05-06T12:00:00+00:00"
  }
  ```

  ```json 404 theme={null}
  {
    "error": true,
    "status_code": 404,
    "error_type": "not_found_error",
    "message": "Patient not found",
    "details": [
      {
        "type": "not_found_error",
        "message": "Patient not found"
      }
    ],
    "timestamp": "2026-05-06T12:00:00+00:00"
  }
  ```

  ```json 422 theme={null}
  {
    "error": true,
    "status_code": 422,
    "error_type": "validation_error",
    "message": "Request validation failed (1 error)",
    "details": [
      {
        "type": "missing",
        "message": "Field required",
        "field": "patient_id",
        "location": ["body", "patient_id"],
        "input_value": null
      }
    ],
    "timestamp": "2026-05-06T12:00:00+00:00"
  }
  ```

  ```json 429 theme={null}
  {
    "error": true,
    "status_code": 429,
    "error_type": "server_error",
    "message": "Rate limit exceeded",
    "details": [
      {
        "type": "rate_limit",
        "message": "Too many requests; retry after backoff"
      }
    ],
    "timestamp": "2026-05-06T12:00:00+00:00"
  }
  ```

  ```json 500 theme={null}
  {
    "error": true,
    "status_code": 500,
    "error_type": "internal_server_error",
    "message": "An internal server error occurred",
    "details": [
      {
        "type": "internal_server_error",
        "message": "An unexpected error occurred while processing your request"
      }
    ],
    "timestamp": "2026-05-06T12:00:00+00:00"
  }
  ```
</ResponseExample>