Meta Ads Asynchronous Reports
To handle large volumes of data, LightLead uses the Meta Ads API's asynchronous reporting mechanism. This makes it possible to retrieve statistics over long periods with detailed breakdowns without exceeding the request execution time limits.
When Asynchronous Reports Are Used
Asynchronous mode is activated automatically in the following cases:
- Large period: requesting data for more than 30 days with daily granularity
- Many breakdowns: using 2+ breakdowns simultaneously
- Large number of fields: the request includes 15+ fields and metrics
- Many entities: the request covers hundreds of campaigns or ads
Indicator: if a synchronous request might exceed the API timeout (typically 60 seconds), LightLead automatically switches to asynchronous mode.
Asynchronous Report Process
Step 1. Creating the Report
LightLead sends a POST request to /act_{ad_account_id}/insights with the async=true parameter. The API returns a report_run_id — a unique report identifier.
Step 2. Checking Status
LightLead periodically checks the report status via a GET request to /{report_run_id}. Possible statuses:
| Status | Description |
|---|---|
Job Not Started | The report has not started generating yet |
Job Started | The report is being generated |
Job Completed | The report is ready to be retrieved |
Job Failed | An error occurred while generating the report |
Job Timeout | Generation time was exceeded |
Step 3. Retrieving Results
Once the status changes to Job Completed, LightLead downloads the data via a GET request to /{report_run_id}/insights.
Parameters of Asynchronous Reports
Level of Detail
Same as in synchronous requests: account, campaign, adset, ad.
Period
date_preset: preset periods (last_7d, last_30d, etc.)time_range: custom date range
Breakdowns
All standard breakdowns are supported. It's recommended to limit yourself to 2-3 breakdowns.
Limitations of Asynchronous Reports
- Report lifetime: results are available for 24 hours after creation
- Maximum period: 37 months
- Concurrent requests: no more than 5 simultaneous asynchronous reports per account
- Request limit: asynchronous reports count toward the overall rate limit
Optimizing Asynchronous Reports
Reducing Data Volume
- Filter before requesting: use campaign and ad filters to narrow the selection
- Limit fields: request only the metrics you need
- Shorten the period: don't request a year of data if you only need a month
Caching Results
LightLead caches the results of asynchronous reports for reuse — see Data Reuse.
Error Handling
| Error | Cause | Solution |
|---|---|---|
Job Failed | Invalid request parameters | Check the parameters and retry |
Job Timeout | Data volume too large | Reduce the period or number of breakdowns |
Rate limit | Request limit exceeded | Wait for the limit to reset |