Troubleshooting Subscription Log Reports

Before You Start: Confirm Scope and Expectations

Report Generation Time Is Variable

Export time depends on dataset size and current platform load. It is normal for some exports to take 5–15 minutes, and in some cases 15+ minutes or longer. There is no fixed SLA for export completion time.

Subscription Log Data Is Eventually Consistent

Subscription events are replicated into the reporting store on a delay (typically replicated about hourly and usually visible around ~3 hours after a subscription starts). Larger delays can occur during backlogs or if your query window/time zone assumptions are off.

Troubleshooting in the Piano UI

Symptom: Blank Screen When Opening or Generating the Report

Try these steps in order:

1. Log out and log back in (refreshes the session).

2. Clear cache and cookies, then hard refresh:

   • Windows: Ctrl + F5 (or Ctrl + Shift + R)

   • Mac: Command + Shift + R

3. Clear site data specifically for piano.io (recommended when issues appear across apps in Visual Analytics).

4. Try an incognito/private window (rules out cached sessions and many extensions).

5. Try a different browser (Chrome is commonly the best baseline).

6. Disable extensions (especially ad blockers/privacy extensions).

Symptom: Export Stays "Queued" in Download Center or Never Appears

• Wait and re-check: Queued exports sometimes complete on their own after a delay.

• Clear cache for piano.io and retry.

• If you deleted a stalled report, wait several hours before retrying to allow background processes to settle.

• If it still does not appear or remains queued for an unusually long time, contact Support with:

  • Approximate time of request

  • Report type and filters used

  • Any visible errors

Symptom: Downloaded File Is Empty

1. Clear cache/cookies and hard refresh.

2. Try incognito/private mode and/or another browser.

3. Disable extensions.

4. Re-check report filters/parameters to ensure they are not excluding all data.

5. Check the browser console for errors during download.

Symptom: Page Fails to Load (Browser-Specific)

If the Subscription Logs screen loads in one browser but not another (for example, works in Chrome but not Safari):

• Clear cache/cookies in the failing browser.

• Try incognito/private mode.

• Update the browser.

• Temporarily disable privacy or blocking features/extensions.

• Restart your computer (can help with local caching/network stack issues).

Troubleshooting via API (Subscription Log Export)

Use the Recommended Endpoint

Schedule Subscription Log exports with:

POST https://reports-api.piano.io/rest/export/schedule/vx/subscriptionLog

Symptom: Export Status Remains CREATED, QUEUED, or IN_PROGRESS

This usually indicates the job is still running (or waiting for capacity).

Recommended approach:

1. Do not block on the initial request. Treat export generation as asynchronous.

2. Poll for status using the status endpoint (for example, every ~30 seconds).

3. Increase client timeouts: Some exports can take 30+ minutes in extreme cases.

4. Avoid duplicate requests with identical parameters — duplication checks can prevent parallel generation and may make it look "stuck."

5. If delays are frequent, schedule exports off-peak and/or reduce request frequency.

Helpful endpoints:

• Check status: https://reports-api.piano.io/rest/export/status

• Retrieve download URL: https://reports-api.piano.io/rest/export/download/url

Symptom: Repeated Timeouts in Your Client Code

Mitigations:

• Narrow the date range (smaller exports complete faster).

• Chunk requests into smaller windows and merge results downstream.

• The Subscription Log export supports daily windows; if you need smaller slices, split by date range as tightly as possible and process incrementally.

• Implement retry with backoff and status polling instead of long single requests.

Symptom: Data Appears Delayed (Missing "Recent" Subscriptions)

1. Confirm timestamps are UTC. Subscription Log uses UTC timestamps; local-time comparisons can exaggerate perceived delays.

2. When running frequent exports, use an overlap window to capture late-arriving records:

   • Example strategy: set start_date_from to 48 hours earlier than your last successful run, then deduplicate by subscription_id + event_time (or your internal unique key strategy).

3. If you suspect replication lag, compare results across time windows; if the same export later contains the missing events, it was likely latency rather than filtering.

Symptom: Same export_id Returned Even When Parameters Change

This can indicate an issue in export generation or parameter handling. Validate that:

• Your request parameters are truly changing (including file_name if you set it).

• You are not unintentionally replaying the same request.

If it continues, contact Support and include:

• Request URL (redact api_token)

• Timestamps and returned export_id values

• Status responses you observed

Validate Inputs and Permissions

Verify API Parameters

At minimum, confirm:

• aid is correct.

• api_token is valid and authorized.

• Your date filters (for example start_date_from, start_date_to) are valid and in the expected format/time zone.

Verify UI Permissions

If you cannot access the Subscription Log screens or downloads:

• Confirm your user role includes permissions to view/export reports.

• Check with colleagues to see whether the issue is account-specific or system-wide.

When to Contact Support (and What to Provide)

Contact Support if:

• An export remains in CREATED/QUEUED/IN_PROGRESS for an unusually long period.

• The UI consistently shows blank screens or exports never appear.

• You consistently receive empty files with correct filters.

• You suspect a platform backlog (especially if multiple users are affected).

Include the following information:

• Affected aid and application name.

• Export endpoint used.

• Request parameters (redact tokens).

• export_id and status polling results.

• Approximate timestamps (UTC preferred).

• Screenshots/screen recording + browser console logs (for UI issues).

Last updated: June 26, 2026