Export Organization Report

Overview

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

Create an export using the exportOrganizationReport mutation.
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

Authentication: Use a Service Account token.
Permissions: Ensure your token has permission to export organization reports.
Organization ID: Identify the organization for which you want to export reports.
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 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.

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:

{
  "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.

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

Variables example:

{
  "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

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

Example Response (Mutation)

{
  "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)

{
  "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)

{
  "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:

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.