From 80707d97d9286eaaf89fee5ebcb5fb507c7ab5b1 Mon Sep 17 00:00:00 2001
From: Lauryn Menard <lauryn@zulip.com>
Date: Mon, 5 Aug 2024 19:06:40 +0200
Subject: [PATCH] api-docs: Revise descriptions of RealmExport schema fields.

---
 zerver/openapi/zulip.yaml | 33 +++++++++++++++++++++++----------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 4ca14ce934..c9e08aecff 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -20909,41 +20909,54 @@ components:
       type: object
       additionalProperties: false
       description: |
-        Object containing details about a realm export.
+        Object containing details about a
+        [data export](/help/export-your-organization).
       properties:
         id:
           type: integer
           description: |
-            The ID of the export.
+            The ID of the data export.
         acting_user_id:
           type: integer
           description: |
-            The ID of the user who did the export.
+            The ID of the user who created the data export.
         export_time:
           type: number
           description: |
-            The UNIX timestamp of when the export was made.
+            The UNIX timestamp of when the data export was started.
         deleted_timestamp:
           type: number
           nullable: true
           description: |
-            The timestamp of when the export was deleted.
-            If `null`, it wasn't deleted.
+            The UNIX timestamp of when the data export was deleted.
+
+            Will be `null` if the data export has not been deleted.
         failed_timestamp:
           type: number
           nullable: true
           description: |
-            The timestamp of when the export failed.
-            If `null`, it didn't fail.
+            The UNIX timestamp of when the data export failed.
+
+            Will be `null` if the data export succeeded, or if it's
+            still being generated.
         export_url:
           type: string
           nullable: true
           description: |
-            The URL of the export. `null` if there's no URL.
+            The URL to download the generated data export.
+
+            Will be `null` if the data export failed, or if it's
+            still being generated.
         pending:
           type: boolean
           description: |
-            Whether the export is pending or not.
+            Whether the data export is pending, which indicates it
+            is still being generated, or if it succeeded, failed or
+            was deleted before being generated.
+
+            Depending on the size of the organization, it can take
+            anywhere from seconds to an hour to generate the data
+            export.
     UserGroup:
       type: object
       additionalProperties: false