Reference Guide
Start typing to search…

Report Tasks

Generate and monitor asynchronous report tasks for campaign analytics

Report Tasks

Generate asynchronous reports for campaign performance, creative analytics, and advertiser metrics through the report domain.

Workflow

  1. List Definitions → Find available report types
  2. Generate Task → Submit report request with parameters
  3. Poll Status → Monitor task progress
  4. Download → Retrieve completed report data

List Report Definitions

query GetReportDefinitions($filter: JSON) {
  report {
    report_defs(filter: $filter) {
      edges {
        report_definition_name
        report_definition_description
        report_definition_type
        report_definition_system
        report_definition_body
      }
      total_count
    }
  }
}

Generate Report

mutation GenerateReport($task: ReportTaskInput!) {
  report {
    generate_report(task: $task) {
      task_id
      task_status
      task_start_time
      task_end_time
    }
  }
}

Variables:

sjach:TODO te metryki sa nie poprawne - trzeba je wziac wpierw z definicji raportu pobrać 0 nie są scisle typowane w API

{
  "task": {
    "report_definition_name": "campaign_performance",
    "report_name": "Campaign Performance Report - January 2025",
    "attributes": {
      "date_range": {
        "kind": "FIXED",
        "date_from": "2025-01-01",
        "date_to": "2025-01-31"
      },
      "filters": [
        {
          "field": "lineitem_type",
          "operator": "=",
          "value": "DISPLAY"
        }
      ],
      "split": ["date", "lineitem_id"],
      "metric": ["impressions", "clicks", "spend", "ctr"]
    }
  }
}

Check Status

query GetTaskStatus($taskId: Int!) {
  report {
    report_task(task_id: $taskId) {
      task_id
      task_status
      task_progress
      task_created_at
      task_completed_at
      task_download_url
      task_error_message
      task_result_count
    }
  }
}

Complete Example (JavaScript)

async function generateAndDownloadReport(reportParams) {
  // 1. Generate report task
  const generateQuery = `
    mutation GenerateReport($input: ReportTaskAttrInput!) {
      report {
        generate_report(report_task_attr: $input) {
          task_id
          task_status
        }
      }
    }
  `;

  const generateResponse = await fetch(API_URL, {
    method: 'POST',
    headers: AUTH_HEADERS,
    body: JSON.stringify({
      query: generateQuery,
      variables: { input: reportParams }
    })
  });

  const generateData = await generateResponse.json();
  const taskId = generateData.data.report.generate_report.task_id;
  
  console.log('Report task created:', taskId);

  // 2. Poll for completion
  const statusQuery = `
    query GetTaskStatus($taskId: Int!) {
      report {
        report_task(task_id: $taskId) {
          task_id
          task_status
          task_progress
          task_download_url
          task_error_message
        }
      }
    }
  `;

  let completed = false;
  let attempts = 0;
  const maxAttempts = 60;

  while (!completed && attempts < maxAttempts) {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds

    const statusResponse = await fetch(API_URL, {
      method: 'POST',
      headers: AUTH_HEADERS,
      body: JSON.stringify({
        query: statusQuery,
        variables: { taskId }
      })
    });

    const statusData = await statusResponse.json();
    const task = statusData.data.report.report_task;

    console.log(`Status: ${task.task_status}, Progress: ${task.task_progress}%`);

    if (task.task_status === 'COMPLETED') {
      console.log('Report ready! Downloading...');
      return task.task_download_url;
    }

    if (task.task_status === 'FAILED') {
      throw new Error(`Report failed: ${task.task_error_message}`);
    }

    attempts++;
  }

  throw new Error('Report generation timeout');
}

// Usage
const downloadUrl = await generateAndDownloadReport({
  report_def_id: 1,
  date_from: "2025-01-01",
  date_to: "2025-01-31",
  filters: {
    lineitem_type: {"=": "DISPLAY"}
  }
});

console.log('Download report from:', downloadUrl);

Next Steps