Async Jobs

Reportkey exposes two async job surfaces:

  • read-only job status endpoints;
  • generation and export job endpoints for starting work and polling status.

What is available today

  • GET /api/v1/projects/{project_id}/reports
  • GET /api/v1/reports/{report_id}
  • GET /api/v1/projects/{project_id}/jobs
  • GET /api/v1/jobs/{job_id}
  • POST /api/v1/projects/{project_id}/generation-jobs
  • GET /api/v1/generation-jobs/{generation_job_id}
  • POST /api/v1/reports/{report_id}/export-jobs
  • GET /api/v1/export-jobs/{export_job_id}
  • GET /api/v1/export-jobs/{export_job_id}/download

Generation flow

POST /api/v1/projects/{project_id}/generation-jobs starts a one-time report generation job.

  • Send Authorization: Bearer ... and Idempotency-Key: ....
  • Send JSON with period.current.from and period.current.to.
  • Include period.compare.from and period.compare.to together or omit them both.
  • Send only the fields documented in the request schema.
  • The API responds with 202 and a Location header pointing to the durable generation job resource.

Poll GET /api/v1/generation-jobs/{generation_job_id} until the status becomes completed.

  • queued: accepted and waiting to run.
  • running: processing has started.
  • completed: result.report_id is available.
  • blocked: the job cannot continue until the blocking issue is resolved.
  • failed: the job ended with an error.

Common blocking and failure reasons include:

  • reauth_required
  • resource_missing
  • no_connected_systems
  • tariff_restricted
  • project_archived
  • generation_failed

Export flow

POST /api/v1/reports/{report_id}/export-jobs starts a PDF or DOC export job.

  • Send Authorization: Bearer ... and Idempotency-Key: ....
  • Send JSON with format: pdf or format: doc.
  • The report must already be readable and ready for export.
  • If an export already exists or is already in flight for the same report and format, the API can reuse the existing job.
  • The API responds with 202 and a Location header pointing to the durable export job resource.

Poll GET /api/v1/export-jobs/{export_job_id} until the status becomes completed.

  • queued: export is waiting to start.
  • running: export is being prepared.
  • completed: the export artifact metadata is available.
  • blocked: the source report cannot be exported yet.
  • failed: the export ended with an error.

Common blocking and failure reasons include:

  • report_not_ready_for_export
  • source_artifact_missing
  • export_generation_failed
  • artifact_unavailable

Download behavior

GET /api/v1/export-jobs/{export_job_id}/download is the protected delivery path for completed export jobs.

  • Use the same bearer token that can read the export job.
  • The API may stream the artifact directly or respond with a temporary redirect.
  • Calling download before the artifact is ready returns 409 artifact_not_ready.

Job payloads

  • Generation jobs expose blocked, failure, and result.
  • Export jobs expose blocked, failure, and artifact.
  • Poll the documented fields instead of relying on undocumented status details.
  • Read Best Practices for idempotency and retry posture.
  • Read Reference for the full endpoint catalog and response shapes.