---
agentTools:
  projectIndex: https://developers.pipefy.com/llms.txt
---

# Export Organization Report

How to create and retrieve an organization report export using GraphQL

## Overview

This guide explains how to **export organization reports** using Pipefy's GraphQL API. The process involves two steps:

1. **Create an export** using the `exportOrganizationReport` mutation.
2. **Retrieve the export** using the `organizationReportExport` query.

This flow allows you to request an export and then fetch its status and download link once processing is complete.

## Prerequisites

1. **Authentication**: Use a [Service Account token](https://developers.pipefy.com/reference/service-accounts).
2. **Permissions**: Ensure your token has permission to export organization reports.
3. **Organization ID**: Identify the organization for which you want to export reports.
4. **Pipe IDs** (optional): Identify the specific pipes to include in the export.

## Step 1: Find Your Organization ID

### 1. Via Pipefy UI

* Open the Organization in your browser.
* The URL will include the Organization ID: `https://app.pipefy.com/organizations/123456789`.
* **Organization ID = `123456789`** (the number after `/organizations/`).

### 2. Via GraphQL Query

* Refer to our [Get resource IDs page](https://developers.pipefy.com/reference/get-resource-ids) for alternative methods.

## Step 2: Create an Organization Report Export

Use the `exportOrganizationReport` mutation to request an export. You must provide the `organizationId` and can optionally include filters, sorting, and specific columns.

```graphql
mutation ExportOrganizationReport(
  $organizationId: Int!
  $pipeIds: [Int!]
  $columns: [String!]
  $filter: ReportCardsFilter
  $sortBy: ReportSortDirectionInput
  $organizationReportId: Int
) {
  exportOrganizationReport(
    input: {
      organizationId: $organizationId
      pipeIds: $pipeIds
      columns: $columns
      filter: $filter
      sortBy: $sortBy
      organizationReportId: $organizationReportId
    }
  ) {
    organizationReportExport {
      id
      state
      startedAt
      finishedAt
      fileURL
      requestedBy {
        id
        name
      }
    }
  }
}
```

**Variables example:**

```json
{
  "organizationId": 123456789,
  "pipeIds": [987654321, 987654322],
  "columns": ["title", "status", "assignee", "due_date", "priority"],
  "filter": {
    "operator": "and",
    "queries": [
      {
        "field": "status",
        "operator": "contains",
        "value": ["in_progress", "review"]
      }
    ]
  },
  "sortBy": {
    "field": "due_date",
    "direction": "asc"
  }
}
```

### Arguments Explained

#### Required Arguments

* **`organizationId`**: The organization ID for the export

#### Optional Arguments

* **`pipeIds`**: Array of pipe IDs to include in the export (defaults to all accessible pipes)
* **`columns`**: Array of field names to include as columns in the exported XLSX file
* **`filter`**: Complex filter object to limit which cards are included in the export
* **`sortBy`**: Object defining how results are sorted in the exported file
  * `field`: The field name to sort by (e.g., "due\_date", "priority", "created\_at")
  * `direction`: Sort direction (`asc` for ascending, `desc` for descending)
* **`organizationReportId`**: Reference to a previously saved report configuration

### Key Fields Returned

* **`id`**: The unique identifier for the export job. Use this to query the export status later.
* **`state`**: The current status of the export job (`processing`, `done`, `failed`).
* **`fileURL`**: The URL to download the export file (available when state is `done`).
* **`startedAt`**: Timestamp when the export processing began.
* **`finishedAt`**: Timestamp when the export processing completed.
* **`requestedBy`**: Information about the user who requested the export.

## Step 3: Retrieve the Organization Report Export

After creating the export, use the `organizationReportExport` query to check the status and retrieve the download link.

```graphql
query OrganizationReportExport($id: ID!) {
  organizationReportExport(id: $id) {
    id
    state
    startedAt
    finishedAt
    fileURL
    requestedBy {
      id
      name
    }
    report {
      id
      name
    }
  }
}
```

**Variables example:**

```json
{
  "id": "export-uuid-123"
}
```

### Key Fields Returned

* **`id`**: The export job identifier.
* **`state`**: The current status (`processing`, `done`, `failed`).
* **`fileURL`**: The URL to download the export file (present when state is `done`).
* **`startedAt`**: Timestamp when processing began.
* **`finishedAt`**: Timestamp when processing completed.
* **`requestedBy`**: User information for the export requester.
* **`report`**: Associated organization report information (if applicable).

## Example Flow

1. **Run the mutation** to create an export and note the returned `id`.
2. **Poll the query** with the `id` until `state` is `done` or `failed`.
3. **Download the file** from `fileURL` when available.

## Example Response (Mutation)

```json
{
  "data": {
    "exportOrganizationReport": {
      "organizationReportExport": {
        "id": "export-uuid-123",
        "state": "processing",
        "startedAt": null,
        "finishedAt": null,
        "fileURL": null,
        "requestedBy": {
          "id": "user-456",
          "name": "John Doe"
        }
      }
    }
  }
}
```

## Example Response (Query - Processing)

```json
{
  "data": {
    "organizationReportExport": {
      "id": "export-uuid-123",
      "state": "processing",
      "startedAt": "2024-03-13T15:30:00Z",
      "finishedAt": null,
      "fileURL": null,
      "requestedBy": {
        "id": "user-456",
        "name": "John Doe"
      },
      "report": {
        "id": "456789123",
        "name": "Sales Pipeline Report"
      }
    }
  }
}
```

## Example Response (Query - Finished)

```json
{
  "data": {
    "organizationReportExport": {
      "id": "export-uuid-123",
      "state": "done",
      "startedAt": "2024-03-13T15:30:00Z",
      "finishedAt": "2024-03-13T15:35:00Z",
      "fileURL": "https://files.pipefy.com/exports/export-uuid-123.csv",
      "requestedBy": {
        "id": "user-456",
        "name": "John Doe"
      },
      "report": {
        "id": "456789123",
        "name": "Sales Pipeline Report"
      }
    }
  }
}
```

## Filter Structure

The `filter` argument supports complex filtering with the following structure:

```graphql
filter: {
  operator: and | or
  queries: [
    {
      field: String      # Field name to filter on
      operator: String   # Filter operator (eq, not_eq, contains, etc.)
      value: Any         # Filter value(s)
    }
  ]
  groups: [              # Nested filter groups
    {
      operator: and | or
      queries: [...]
    }
  ]
}
```

## Notes

* **Processing Time**: The export process may take several minutes depending on the data size and complexity of filters.
* **File Format**: Exports are generated as XLSX files.
* **URL Expiry**: The `fileURL` has a limited lifespan (typically one hour).
* **Email Notification**: The requester will receive an email once the export is ready for download.
* **Column Selection**: If no `columns` are specified, all available fields will be included in the export, if there is the report reference; otherwise, it will include no columns.