Reporting & Analytics

Generate campaign performance reports and access analytics data through the report domain. The ADP API uses an asynchronous report generation workflow.

Overview

The Reporting API provides:

Report Generation - Create asynchronous report tasks
Task Status - Monitor report generation progress
Data Retrieval - Download completed reports
Scheduled Reports - Automate regular reporting

Asynchronous Workflow

Reports are generated asynchronously because they may process large amounts of data.

sequenceDiagram
    participant Client
    participant API
    participant ReportEngine
    
    Client->>API: 1. generate_report mutation
    API->>ReportEngine: Create task
    API-->>Client: Return task_id
    
    ReportEngine->>ReportEngine: Process data
    
    Client->>API: 2. report_task query (check status)
    API-->>Client: Status: PROCESSING
    
    Client->>API: 3. report_task query (check again)
    API-->>Client: Status: COMPLETED + download_url
    
    Client->>API: 4. Download report
    API-->>Client: Report data (CSV/JSON)

Workflow Steps

Generate - Submit generate_report mutation → receive task_id
Monitor - Poll report_task query with task_id → check status
Download - When status = COMPLETED, use task_download_url
Retrieve - Download report data

Quick Start

1. List Available Report Definitions

query GetReportDefinitions {
  report {
    report_defs {
      edges {
        report_definition_name
        report_definition_description
        report_definition_type
      }
      total_count
    }
  }
}

Response:

{
  "data": {
    "report": {
      "report_defs": {
        "edges": [
          {
            "report_definition_name": "campaign_performance",
            "report_definition_description": "Daily campaign metrics",
            "report_definition_type": "STANDARD"
          },
          {
            "report_definition_name": "creative_performance",
            "report_definition_description": "Creative-level analytics",
            "report_definition_type": "STANDARD"
          }
        ],
        "total_count": 2
      }
    }
  }
}

2. Generate Report Task

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

Variables:

{
  "task": {
    "report_definition_name": "campaign_performance",
    "report_name": "Campaign Performance Report - January 2025",
    "attributes": {
      "date_range": {
        "kind": "STATIC",
        "date_from": "2025-01-01",
        "date_to": "2025-01-31"
      },
      "filters": [
        {
          "field": "lineitem_type",
          "operator": "=",
          "value": "DISPLAY"
        }
      ]
    }
  }
}

Response:

{
  "data": {
    "report": {
      "generate_report": {
        "task_id": 12345,
        "task_status": "PENDING",
        "task_start_time": "2025-01-15T10:30:00Z"
      }
    }
  }
}

3. Check Task Status

query GetReportTaskStatus($taskId: Int!) {
  report {
    report_task(task_id: $taskId) {
      task_id
      task_status
      task_progress
      task_download_url
      task_error_message
    }
  }
}

Variables:

{
  "taskId": 12345
}

Response (processing):

{
  "data": {
    "report": {
      "report_task": {
        "task_id": 12345,
        "task_status": "PROCESSING",
        "task_progress": 45,
        "task_download_url": null,
        "task_error_message": null
      }
    }
  }
}

Response (completed):

{
  "data": {
    "report": {
      "report_task": {
        "task_id": 12345,
        "task_status": "COMPLETED",
        "task_progress": 100,
        "task_download_url": "https://adp-api.dreamlab.pl/reports/download/12345",
        "task_error_message": null
      }
    }
  }
}

4. Download Report

curl -X GET \
  -H "x-internal-auth-login: YOUR_CLIENT_LOGIN" \
  -H "x-internal-auth-token: YOUR_CLIENT_TOKEN" \
  "https://adp-api.dreamlab.pl/reports/download/12345" \
  -o report.csv

Task Statuses

Status	Description	Next Action
`PENDING`	Task created, waiting to start	Wait and poll
`PROCESSING`	Report generation in progress	Wait and poll
`COMPLETED`	Report ready for download	Download from `task_download_url`
`FAILED`	Report generation failed	Check `task_error_message`
`CANCELLED`	Task cancelled by user	N/A

Polling Best Practices

Recommended Polling Interval

async function waitForReportCompletion(taskId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const task = await checkReportTask(taskId);
    
    if (task.task_status === 'COMPLETED') {
      return task.task_download_url;
    }
    
    if (task.task_status === 'FAILED') {
      throw new Error(task.task_error_message);
    }
    
    // Wait 5 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
  
  throw new Error('Report generation timeout');
}

Polling Guidelines

Initial delay: Wait 5 seconds before first poll
Poll interval: 5-10 seconds for normal reports
Long reports: 30 seconds for large date ranges
Max attempts: 60 attempts (5 minutes total)
Exponential backoff: Optional for very long reports

Common Report Types

Campaign Performance Report

{
  "report_definition_name": "campaign_performance",
  "report_name": "Campaign Performance - January 2025",
  "attributes": {
    "date_range": {
      "kind": "STATIC",
      "date_from": "2025-01-01",
      "date_to": "2025-01-31"
    },
    "split": ["date", "lineitem_id"],
    "metric": ["impressions", "clicks", "spend"]
  }
}

Creative Performance Report

{
  "report_definition_name": "creative_performance",
  "report_name": "Creative Performance - January 2025",
  "attributes": {
    "date_range": {
      "kind": "STATIC",
      "date_from": "2025-01-01",
      "date_to": "2025-01-31"
    },
    "split": ["creative_id"],
    "metric": ["impressions", "clicks", "ctr"]
  }
}

Advertiser Summary Report

{
  "report_definition_name": "advertiser_summary",
  "report_name": "Advertiser Summary - January 2025",
  "attributes": {
    "date_range": {
      "kind": "STATIC",
      "date_from": "2025-01-01",
      "date_to": "2025-01-31"
    },
    "split": ["advertiser_id"],
    "metric": ["impressions", "clicks", "conversions", "spend"]
  }
}

Next Steps

Report Tasks - Complete API reference
Inventory Management - Configure ad units
Delivery APIs - Manage campaigns

Getting Started - Authentication basics
Filtering - Filter report data

Reporting & Analytics

Overview

Asynchronous Workflow

Workflow Steps

Quick Start

1. List Available Report Definitions

2. Generate Report Task

3. Check Task Status

4. Download Report

Task Statuses

Polling Best Practices

Recommended Polling Interval

Polling Guidelines

Common Report Types

Campaign Performance Report

Creative Performance Report

Advertiser Summary Report

Next Steps

Related