Export Pipe Audit Logs Report

⚠️
BETA - This API is currently in beta testing. If you encounter issues or have feedback, contact our support team.

Overview

The exportPipeAuditLogsReport mutation creates an asynchronous export job that fetches pipe audit logs and delivers a downloadable report file. You can filter by activity type, date range, and user, and choose between CSV and JSONL output formats.

The export is delivered in one of two ways:

Email (default): a download link is sent to the requesting user's email once processing is complete.
Webhook: a push notification is sent to the configured webhook endpoint as soon as processing completes. The download URL is available via the auditLogExportRequest query using the correlationId.

Prerequisites

Authentication: This mutation requires the id_token from your Pipefy session cookie to authenticate requests to the activities service.
Permissions: The authenticated user must have the pipe admin role on the target pipe.
Pipe UUID: You must know the UUID of the pipe you want to export logs for. See Get resource IDs.

Mutation Reference

Full signature

mutation ExportPipeAuditLogsReport(
  $pipeUuid: ID!
  $auditLogType: AuditLogTypeEnum
  $outputFormat: AuditLogOutputFormat
  $deliveryMethod: AuditLogDeliveryMethod
  $searchTerm: String
  $filterDateFrom: DateTime
  $filterDateTo: DateTime
) {
  exportPipeAuditLogsReport(input: {
    pipeUuid: $pipeUuid
    auditLogType: $auditLogType
    outputFormat: $outputFormat
    deliveryMethod: $deliveryMethod
    searchTerm: $searchTerm
    filterDateFrom: $filterDateFrom
    filterDateTo: $filterDateTo
  }) {
    success
    correlationId
  }
}

Arguments

Argument	Type	Required	Default	Description
`pipeUuid`	`ID`	Yes	—	UUID of the pipe
`auditLogType`	`AuditLogTypeEnum`	No	`null` (all)	Scope export to a specific activity type
`outputFormat`	`AuditLogOutputFormat`	No	`CSV`	File format for the exported report
`deliveryMethod`	`AuditLogDeliveryMethod`	No	`EMAIL`	How the export is delivered
`searchTerm`	`String`	No	`""`	Filter logs by user name or email (case-insensitive)
`filterDateFrom`	`DateTime`	No	30 days ago (beginning of day)	Start of the date range (inclusive)
`filterDateTo`	`DateTime`	No	Yesterday (end of day)	End of the date range (inclusive)

`AuditLogTypeEnum` values

Value	Description
`card_activity`	Activities related to card execution
`configuration_changes`	Activities related to pipe configuration changes
(omitted)	All activity types

`AuditLogOutputFormat` values

Value	Description
`CSV`	Comma-separated values with UTF-8 BOM header
`JSONL`	JSON Lines — one JSON object per line, keyed by the columns listed in Export File Structure

`AuditLogDeliveryMethod` values

Value	Description
`EMAIL`	A download link is sent to the user's email when the export is ready
`WEBHOOK`	A push notification is sent to the configured webhook endpoint; the download URL is retrievable via the `auditLogExportRequest` query

Response fields

Field	Type	Description
`success`	`Boolean`	`true` if the export job was created successfully
`correlationId`	`ID`	Unique identifier for this export request. Use it to poll the `auditLogExportRequest` query when `deliveryMethod` is `WEBHOOK`

Business Rules

Date range

filterDateFrom is normalized to the beginning of the day (00:00:00).
filterDateTo is normalized to the end of the day (23:59:59).
filterDateTo must be after filterDateFrom.
filterDateTo cannot be in the future.
The maximum range between filterDateFrom and filterDateTo is 30 days.
filterDateFrom cannot be older than 180 days from today.

Rate limit

Each user can create at most 6 export requests per day. Exceeding this limit returns a UsageLimitExceededError.

Query Reference — auditLogExportRequest

Use this query to retrieve the full details of an export request by its correlationId.

Signature

query AuditLogExportRequest($correlationId: ID!) {
  auditLogExportRequest(correlationId: $correlationId) {
    correlationId
    status
    outputFormat
    deliveryMethod
    signedUrl
    signedUrlExpiresAt
    dateFrom
    dateTo
    observation
    pipe {
      id
      uuid
      name
    }
  }
}

Arguments

Argument	Type	Required	Description
`correlationId`	`ID`	Yes	Returned by `exportPipeAuditLogsReport`

Response fields

Field	Type	Description
`correlationId`	`ID`	Unique identifier for this export request
`status`	`AuditLogExportStatus`	`PROCESSING`, `FINISHED`, or `FAILED`
`outputFormat`	`AuditLogOutputFormat`	`CSV` or `JSONL`
`deliveryMethod`	`AuditLogDeliveryMethod`	`EMAIL` or `WEBHOOK`
`signedUrl`	`String`	Pre-signed download URL — present only when `status` is `FINISHED` and `deliveryMethod` is `WEBHOOK`
`signedUrlExpiresAt`	`DateTime`	Expiration of the signed URL (up to 7 days)
`dateFrom` / `dateTo`	`DateTime`	Date range that was exported
`observation`	`String`	Error message — present only when `status` is `FAILED`
`pipe`	object	Pipe identity: `id`, `uuid`, `name`

Usage Examples

Minimal — email delivery, all activities, last 30 days

mutation {
  exportPipeAuditLogsReport(input: {
    pipeUuid: "87654321-4321-4321-4321-cba987654321"
  }) {
    success
    correlationId
  }
}

{
  "data": {
    "exportPipeAuditLogsReport": {
      "success": true,
      "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

Filter by activity type and date range

mutation ExportPipeAuditLogsReport(
  $pipeUuid: ID!
  $auditLogType: AuditLogTypeEnum
  $filterDateFrom: DateTime
  $filterDateTo: DateTime
) {
  exportPipeAuditLogsReport(input: {
    pipeUuid: $pipeUuid
    auditLogType: $auditLogType
    filterDateFrom: $filterDateFrom
    filterDateTo: $filterDateTo
  }) {
    success
    correlationId
  }
}

{
  "pipeUuid": "87654321-4321-4321-4321-cba987654321",
  "auditLogType": "card_activity",
  "filterDateFrom": "2025-03-01T00:00:00Z",
  "filterDateTo": "2025-03-30T23:59:59Z"
}

Webhook delivery

The delivery method is independent of the output format — WEBHOOK works with either CSV or JSONL. The example below uses JSONL, but CSV behaves the same way.

When deliveryMethod is WEBHOOK, the signed download URL is not sent by email. You can retrieve it in two ways:

Polling: query auditLogExportRequest using the correlationId until status is finished, then read signedUrl for the download link.
Push notification: configure a pipe webhook with action audit_log.export_finished to receive an HTTP POST as soon as processing completes. The payload contains only correlation_id (and details on failure) — use the correlationId to fetch the full export details, including signedUrl, via auditLogExportRequest. See Audit Log Export Finished for the full payload reference.

Step 1 — Request the export

mutation ExportPipeAuditLogsReport(
  $pipeUuid: ID!
  $outputFormat: AuditLogOutputFormat
  $deliveryMethod: AuditLogDeliveryMethod
) {
  exportPipeAuditLogsReport(input: {
    pipeUuid: $pipeUuid
    outputFormat: $outputFormat
    deliveryMethod: $deliveryMethod
  }) {
    success
    correlationId
  }
}

{
  "pipeUuid": "87654321-4321-4321-4321-cba987654321",
  "outputFormat": "JSONL",
  "deliveryMethod": "WEBHOOK"
}

Step 2 — Poll for status and signed URL

query AuditLogExportRequest($correlationId: ID!) {
  auditLogExportRequest(correlationId: $correlationId) {
    status
    signedUrl
    signedUrlExpiresAt
    pipe {
      id
      uuid
      name
    }
  }
}

{
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Poll until status is finished. The signedUrl field will contain the pre-signed download URL, valid for up to 7 days. The pipe object exposes the id, uuid, and name of the pipe the export belongs to — request only the fields you need.

Export File Structure

Each export contains the following columns, in this order, regardless of the output format:

Column	Description
`Pipe ID`	UUID of the pipe the activity belongs to
`Audit ID`	Unique identifier of the audit log entry
`Timestamp`	When the event occurred (ISO 8601)
`Actor`	Name of the user who performed the action
`User Email`	Email of the actor
`Actor ID`	UUID of the actor
`Actor Type`	Type of actor (`user`, `system`, …)
`Event Name`	Raw event code, e.g. `card.field_value.update`
`Object Type`	Type of the object affected by the event
`Object ID`	Identifier of the object affected
`New value`	Value after the change — may be empty (see note below)
`Old value`	Value before the change — may be empty (see note below)
`Metadata`	Additional event details (JSON)
`Activity Details`	Human-readable description of the activity

Note — empty Old value / New value: These columns are filled only for events whose detail carries a before/after pair (e.g. card.move, pipe.name.update, pipe.sla.update, pipe.card_noun.update, phase.sla.update). There are update events that represent a change but currently return both columns empty — their payload carries only the new/current value, or no before/after pair. Examples include pipe.create_card_button_label.update, label.update, phase.name.update, and connection.update. For these, the change is still described in the Activity Details and Metadata columns, and we're working on populating the missing Old value/New value pairs. Always treat Old value and New value as optional when parsing the export.

CSV example

Pipe ID,Audit ID,Timestamp,Actor,User Email,Actor ID,Actor Type,Event Name,Object Type,Object ID,New value,Old value,Metadata,Activity Details
87654321-4321-4321-4321-cba987654321,a1b2c3d4-e5f6-7890-abcd-ef1234567890,2025-03-15T14:32:00Z,John Doe,[email protected],11111111-2222-3333-4444-555555555555,user,pipe.name.update,Pipe,301234567,Sales Pipeline,Sales,"{""before_value"":""Sales"",""after_value"":""Sales Pipeline""}",Pipe renamed to Sales Pipeline
87654321-4321-4321-4321-cba987654321,b2c3d4e5-f6a7-8901-bcde-f23456789012,2025-03-15T15:10:00Z,Jane Smith,[email protected],66666666-7777-8888-9999-000000000000,user,label.update,Label,409876543,,,"{""label_name"":""Priority""}",Label Priority updated

The label.update row shows the documented behavior: New value and Old value are empty while the change is still captured in Metadata and Activity Details.

JSONL example

{"pipe_id":"87654321-4321-4321-4321-cba987654321","audit_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","timestamp":"2025-03-15T14:32:00Z","actor":"John Doe","user_email":"[email protected]","actor_id":"11111111-2222-3333-4444-555555555555","actor_type":"user","event_name":"pipe.name.update","object_type":"Pipe","object_id":"301234567","new_value":"Sales Pipeline","old_value":"Sales","metadata":{"before_value":"Sales","after_value":"Sales Pipeline"},"activity_details":"Pipe renamed to Sales Pipeline"}
{"pipe_id":"87654321-4321-4321-4321-cba987654321","audit_id":"b2c3d4e5-f6a7-8901-bcde-f23456789012","timestamp":"2025-03-15T15:10:00Z","actor":"Jane Smith","user_email":"[email protected]","actor_id":"66666666-7777-8888-9999-000000000000","actor_type":"user","event_name":"label.update","object_type":"Label","object_id":"409876543","new_value":null,"old_value":null,"metadata":{"label_name":"Priority"},"activity_details":"Label Priority updated"}

In JSONL the Metadata column is emitted as a native JSON object, and empty new_value/old_value are rendered as null.

Error Handling

Common error scenarios

Scenario	Error type	Message
User is not a pipe admin	`Permission denied`	`Permission denied`
`filterDateTo` before `filterDateFrom`	`InvalidInputError`	`filter_date_to must be after filter_date_from`
Date range exceeds 30 days	`InvalidInputError`	`date range cannot exceed 30 days`
`filterDateFrom` older than 180 days	`InvalidInputError`	`filter_date_from cannot be older than 180 days`
`filterDateTo` in the future	`InvalidInputError`	`filter_date_to cannot be in the future`
Daily request limit reached	`UsageLimitExceededError`	`You've reached the daily limit for audit log export requests...`

Error response shape

{
  "data": {
    "exportPipeAuditLogsReport": null
  },
  "errors": [
    {
      "message": "filter_date_to must be after filter_date_from",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["exportPipeAuditLogsReport"]
    }
  ]
}

⚠️BETA - This API is currently in beta testing. If you encounter issues or have feedback, contact our support team.

Overview

Prerequisites

Mutation Reference

Full signature

Arguments

AuditLogTypeEnum values

AuditLogOutputFormat values

AuditLogDeliveryMethod values

Response fields

Business Rules

Date range

Rate limit

Query Reference — auditLogExportRequest

Signature

Arguments

Response fields

Usage Examples

Minimal — email delivery, all activities, last 30 days

Filter by activity type and date range

Webhook delivery

Export File Structure

Error Handling

Common error scenarios

Error response shape

⚠️
BETA - This API is currently in beta testing. If you encounter issues or have feedback, contact our support team.

`AuditLogTypeEnum` values

`AuditLogOutputFormat` values

`AuditLogDeliveryMethod` values