From f953a7ddbbf9d707a500047fbd1954fecbefd040 Mon Sep 17 00:00:00 2001 From: Jacek Pyziak Date: Sun, 22 Feb 2026 09:13:25 +0100 Subject: [PATCH] Refactor code structure for improved readability and maintainability --- .claude/settings.local.json | 3 +- .vscode/ftp-kr.sync.cache.json | 32 ++-- AGENTS.md | 45 ----- TODO.md | 0 temp_fb_authentication.html | 121 ------------- temp_fb_authorization.html | 209 ----------------------- temp_fb_get_started.html | 49 ------ temp_fb_insights_async.html | 303 --------------------------------- temp_fb_system_users.html | 125 -------------- 9 files changed, 22 insertions(+), 865 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 TODO.md delete mode 100644 temp_fb_authentication.html delete mode 100644 temp_fb_authorization.html delete mode 100644 temp_fb_get_started.html delete mode 100644 temp_fb_insights_async.html delete mode 100644 temp_fb_system_users.html diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 4947039..f3a5cf9 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -29,5 +29,6 @@ "statusLine": { "type": "command", "command": "npx -y @owloops/claude-powerline@latest --style=powerline" - } + }, + "outputStyle": "jacek" } diff --git a/.vscode/ftp-kr.sync.cache.json b/.vscode/ftp-kr.sync.cache.json index 5f7620a..5efd7b0 100644 --- a/.vscode/ftp-kr.sync.cache.json +++ b/.vscode/ftp-kr.sync.cache.json @@ -323,7 +323,7 @@ }, "index.php": { "type": "-", - "size": 3891, + "size": 4210, "lmtime": 1771198110809, "modified": true }, @@ -622,15 +622,15 @@ "products": { "main_view.php": { "type": "-", - "size": 49238, - "lmtime": 1771441425576, + "size": 64362, + "lmtime": 1771717398898, "modified": false }, "product_history.php": { "type": "-", - "size": 13214, - "lmtime": 1769467103988, - "modified": true + "size": 13326, + "lmtime": 1771717401282, + "modified": false } }, "site": { @@ -656,8 +656,8 @@ "campaigns": { "main_view.php": { "type": "-", - "size": 20532, - "lmtime": 1771626632932, + "size": 21607, + "lmtime": 1771717394441, "modified": false } }, @@ -678,8 +678,8 @@ "campaign_terms": { "main_view.php": { "type": "-", - "size": 81281, - "lmtime": 1771441788473, + "size": 81511, + "lmtime": 1771717410322, "modified": false } }, @@ -694,8 +694,16 @@ "facebook_ads": { "main_view.php": { "type": "-", - "size": 10785, - "lmtime": 1771619352316, + "size": 10806, + "lmtime": 1771717403326, + "modified": false + } + }, + "logs": { + "main_view.php": { + "type": "-", + "size": 5948, + "lmtime": 1771717396318, "modified": false } } diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 9a85c4c..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,45 +0,0 @@ -# Repository Guidelines - -## Project Structure & Module Organization -adsPRO is a custom PHP MVC app. Keep business logic in: -- `autoload/controls/` (`class.*.php`): request handling (`\controls\*`) -- `autoload/factory/` (`class.*.php`): DB access via Medoo (`\factory\*`) -- `autoload/view/` (`class.*.php`): view composition (`\view\*`) -- `autoload/services/`: external integrations (Google Ads, OpenAI, Claude) -- `templates/`: PHP templates rendered with `\Tpl::view()` -- `migrations/`: SQL migrations (`NNN_description.sql` + optional `demo_data.sql`) -- `layout/`: SCSS/CSS assets (`style.scss` -> `style.css`) - -Main entry points are `index.php`, `ajax.php`, `api.php`, `cron.php`, and `install.php`. - -## Build, Test, and Development Commands -- `php -S 127.0.0.1:8000` - run a local PHP server from repo root. -- `php install.php` - apply pending DB migrations. -- `php install.php --with_demo` - apply migrations and demo data. -- `php install.php --force` - re-apply tracked migrations. -- `php -l autoload/controls/class.Campaigns.php` - lint a changed PHP file. - -There is no dedicated build pipeline; frontend dependencies are committed in `libraries/`. SCSS is typically compiled via VS Code Live Sass Compiler. - -## Coding Style & Naming Conventions -- Follow existing PHP style: spaces inside parentheses (`if ( $x )`), braces on new lines. -- Use `PascalCase` class names, lowercase namespaces (`\controls`, `\factory`), and `snake_case` for methods/variables/DB columns. -- Controllers/factories are conventionally `static public function ...`. -- Keep route/module naming aligned with URL pattern `/module/action/...`. - -## Testing Guidelines -No first-party automated test suite is maintained in this repo. Validate changes with: -- PHP lint on edited files. -- Manual UI checks for affected `templates/` views. -- Endpoint checks for `ajax.php`, `api.php`, or `cron.php` paths you touched. -- Migration dry run on a non-production database when schema is changed. - -Document manual test steps and outcomes in each PR. - -## Commit & Pull Request Guidelines -- Use concise Polish commit messages with prefixes seen in history: `feat:`, `fix:`, `update:`. -- Keep commits focused (feature, refactor, migration, UI tweak). -- PRs should include: scope summary, linked issue/task, migration notes, manual test checklist, and screenshots for UI changes. - -## Security & Configuration Tips -`config.php` contains environment credentials. Do not introduce new secrets in commits or PR discussions, and treat any credential change as a coordinated ops task. diff --git a/TODO.md b/TODO.md deleted file mode 100644 index e69de29..0000000 diff --git a/temp_fb_authentication.html b/temp_fb_authentication.html deleted file mode 100644 index d710c5c..0000000 --- a/temp_fb_authentication.html +++ /dev/null @@ -1,121 +0,0 @@ - - -Authentication - Marketing API - Documentation - Meta for Developers - - - - - - - - - - - - - - - - - -
Marketing API

Authentication

- -

Marketing API calls require an access token to be passed as a parameter in every API call.

- -

See Access Tokens for Meta Technologies for more information on the various types of access tokens.

-

Get an Access Token for Your App

- -

User Access Tokens

- -

Graph API Explorer

- -

You can get a user access token using the Graph API Explorer. To learn how to use the Graph API Explorer to make API calls, see the Graph API Explorer Guide.

- -
    -
  1. In the Meta App field, select an app to obtain the access token for.
    2. -
  2. In the User or Page field, select User Token.
    3. -
  3. In the Add a Permission drop-down under Permissions, select the permissions you need (for example, ads_read and/or ads_management).
    4. -
  4. Click Generate Access Token. The box on top of the button is populated with the access token; store the token for later use.
    5. -
- -

Debug

- -

To get more information in the token you just generated, click on the information icon (i) in front of the token to open the Access Token Info table, which displays some basic information about the token. Click Open in Access Token Tool to be redirected to the Access Token Debugger.

- -

While debugging, you can check:

- -
    -
  • App ID: The app ID mentioned in the prerequisite section.
    • -
  • Expires: A time stamp. A short-lived token expires in an hour or two.
    • -
  • Scopes: Contains the permissions added in the Graph API Explorer.
    • -
- -

Extend your access token

- -
    -
  1. Paste your token in the text box of the Access Token Debugger and click Debug.
    2. -
  2. Click Extend Access Token at the bottom of the Access Token Info table to get a long-lived token, and copy that token for later use.
    3. -
- -

Check your new token’s properties using the Access Token Debugger. It should have a longer expiration time, such as "60 days", or "Never" under Expires. See Long-Lived Access Token for more information.

- -

System User Access Tokens

- -

A system user access token is a type of access token that is associated with a system user account, which is an account that is created in Meta Business Manager for the purpose of managing assets and calling the Marketing API. System user access tokens are useful for server-to-server interactions where there is no user present to authenticate. They can be used to perform actions on behalf of the business, such as reading and writing business data, managing ad campaigns, and other ad objects.

- -

One benefit of using a system user access token is that it does not expire, so it can be used in long-running scripts or services that need to access the Marketing API. Additionally, because system user accounts are not tied to a specific individual, they can be used to provide a level of separation between personal and business activity on Meta technologies.

- -

System user tokens are also less likely subject to invalidation for other reasons compared to the long-lived user access tokens.

- -

See System Users for more information.

-

Get an Access Token for Ad Accounts you Manage

- -

After the owner of an ad account you are going to manage clicks the Allow button when you prompt for permissions, they are redirected to a URL that contains the value of the redirect_uri parameter and an authorization code:

-
-http://YOUR_URL?code=<AUTHORIZATION_CODE>
-

You can then build the URL for an API call that includes the endpoint for getting a token, your app ID, your site URL, your app secret, and the authorization code you just received:

-
-https://graph.facebook.com/v25.0/oauth/access_token?
-  client_id=<YOUR_APP_ID>
-  &redirect_uri=<YOUR_URL>
-  &client_secret=<YOUR_APP_SECRET>
-  &code=<AUTHORIZATION_CODE>
-

The API response should contain the generated access token:

- -
    -
  • If you follow the server-side authentication flow, you get a persistent token.
    • -
  • If you follow the client-side authentication flow, you get a token with a finite validity period of about one to two hours. This can be exchanged for a persistent token by calling the Graph API endpoint for Extending Tokens.
    • -
- -

If the API is to be invoked by a system user of a business, you can use a system user access token.

- -

You can debug the access token, check for expiration, and validate the permissions granted using the access token debugger or the programmatic validation API.

-

Storing the Token

- -

Your token should be safely stored in your database for subsequent API calls. Moving tokens between your client and server must be done securely over HTTPS to ensure account security. Read more about the implications of moving tokens between your clients and your server.

- -

You should regularly check for validity of the token, and if necessary, prompt for permissions renewal. Even a persistent token can become invalid in a few cases, including the following:

- -
    -
  • A password changes
    • -
  • Permissions are revoked
    • -
- -

As user access tokens can be invalidated or revoked anytime for some reasons, your app should expect to have a flow to re-request permission from users. Check the validity of the user token when they start your app. If necessary, re-run the authentication flow to get an updated token.

- -

If this is not possible for your app, you may need a different way to prompt for permissions. This can happen in cases where the API calls are not directly triggered by a user interface or are made by periodically run scripts. A possible solution is to send an email with instructions.

-

Best Practices for Secure Credential Management

- -

To ensure the security of user credentials and access tokens, you should adhere to the following best practices:

- -
    -
  • Use HTTPS: Always transmit access tokens over secure connections (HTTPS) to prevent interception by malicious actors.
    • -
  • Store Tokens Securely: Utilize secure storage solutions, such as encrypted databases, for storing access and refresh tokens, minimizing the risk of unauthorized access.
    • -
  • Limit Token Scope: Request only the minimum necessary permissions, reducing the risk of overexposure to user data.
    • -
  • Implement Token Expiration: Regularly refresh tokens and have a robust mechanism to handle expiration, ensuring continued access without exposing long-lived tokens.
    • -
-

Learn More

-
- - - diff --git a/temp_fb_authorization.html b/temp_fb_authorization.html deleted file mode 100644 index 65b5eb9..0000000 --- a/temp_fb_authorization.html +++ /dev/null @@ -1,209 +0,0 @@ - - -Authorization - Marketing API - Documentation - Meta for Developers - - - - - - - - - - - - - - -
Marketing API

Authorization

- -

The authorization process verifies the users and apps that will be accessing the Marketing API and grants them permissions.

-

App Roles

- -

In your app's dashboard, you can set roles for yourself or team members as necessary: Admin, Developer, Tester.

- -

Note: Depending on your intended use case, you may need to submit your app for review to gain access to specific permissions related to ad management.

-

Access Levels, Permissions, and Features

- -

Business apps are subject to an additional layer of Graph API authorization called access levels. During App Review, your app must also request specific permissions and features.

-

All developers must follow all Meta Platform Terms and Developer Policies. Calls on ANY access level are against production data.

-

Marketing API Access Levels vs. Ads Management Standard Access

-

Permissions and features for apps have two different access levels: standard access and advanced access (Note: The use of the term "standard access" here is not related to the Ads Management Standard Access feature.) The advanced access level of Ads Management Standard Access still requires an app to pass through review in order to have access to the feature.

Marketing API Access vs Ads Management Standard Access Mapping

-
Marketing API AccessAds Management Standard AccessAction

Development access

-

Standard access

-

By default

-

Standard access

-

Advanced access

-

Apply in App Dashboard

-

To check your current access level, go to App Dashboard > App Review > Permissions and Features.

- -

Permissions and Features

- -

Permissions

- -

The permissions you should request change depending on which API you want to access.

- -

If your app is only managing your ad account, standard access to the ads_read and ads_management permissions are sufficient. If your app is managing other people's ad accounts, you need advanced access to the ads_read and/or ads_management permissions. See all available permissions for business apps.

- -

Features

- -

The features you should request change depending on how you want to use our APIs. If you're managing ads, a common feature to request is Ads Management Standard Access. See all available features for business apps.

- -
Feature access levels
-
Feature Access LevelDescription

Standard access

-

Business apps are automatically approved for standard access for all permissions and features available to the Business app type.

- -

Use this option if you're getting started. You can build end-to-end workflows before requesting full permissions, and you can access an unlimited number of ad accounts.

- -

Some API calls may not be available with standard access because they may belong to multiple accounts or the affected account can't be identified programmatically.

-

Advanced access

-

Advanced access must be approved through the App Review process on an individual permission and feature basis.

- -
    -
  1. To request advanced access, go to your app’s dashboard and click App Review > Permissions and Features.
    2. -
  2. Find the permission or feature you would like to access and, under Action, click Request advanced access. You can select one or more features. Once you have selected your options, click Continue the Request. You'll be taken to a screen that guides you through the submission process.
    3. -
- -

After you submit your information, Meta responds with an approval or denial and additional information if your app is not qualified for standard access.

- -

If you're approved for advanced access, you need to do the following to maintain your status:

- -
    -
  • Have successfully made at least 1500 Marketing API calls in the last 15 days.
    • -
  • Have made Marketing API calls with an error rate of less than 15% in the last 15 days.
    • -
-
Access level significance
- -

The table below shows how standard and advanced access levels impact the Ads Management Standard Access feature.

-
-Standard Access - -Advanced Access -

Account Limits

-

Manage an unlimited number of ad accounts. App admins or developers can make API calls on behalf of ad account admins or advertisers.

-

Manage an unlimited number of ad accounts, assuming you get ads_read or ads_management permission from the ad account.

-

Rate Limits

-

Heavily rate-limited per ad account. For development only. Not for production apps running for live advertisers.

-

Lightly rate limited per ad account.

-

Business Manager

-

Limited access to Business Manager and Catalog APIs. No Business Manager access to manage ad accounts, user permissions and Pages.

-

Access to all Business Manager and Catalog APIs.

-

System User

-

Can create 1 system user and 1 admin system user.

-

Can create 10 system users and 1 admin system user.

-

Page Creation

-

Cannot create Pages through the API.

-

Cannot create Pages through the API.

-
Get Advanced Access
- -

In order to get advanced access of Ads Management Standard Access, your app needs to meet these requirements:

- -
    -
  • Have successfully made at least 1500 Marketing API calls in the last 15 days.
    • -
  • Have made Marketing API calls with an error rate of less than 15% in the last 15 days.
    • -
- -

If you're managing someone's ads, use the scope parameter to prompt them for the ads_management or ads_read permissions. Your app gets access when they click Allow.

-
-https://www.facebook.com/v25.0/dialog/oauth?
-  client_id=<YOUR_APP_ID>
-  &redirect_uri=<YOUR_URL>
-  &scope=ads_management
-

Note: When inputting the YOUR_URL field, put a trailing / (for example, http://www.facebook.com/).

- -
Example Use Cases
-
Use CaseWhat To Request

You want to read and manage ads for ad accounts you own or have been granted access to by the ad account owner.

-
    -
  • Permission: ads_management
    • -
  • Feature: Ads Management Standard Access
    • -
-

You want to read ad reports for ad accounts you own or have been granted access to by the ad account owner.

-
    -
  • Permission: ads_read
    • -
  • Feature: Ads Management Standard Access
    • -
-

You want to pull ad reports from a set of clients and to both read and manage ads from another set of clients.

-
    -
  • Permissions: ads_management and ads_read
    • -
  • Feature: Ads Management Standard Access
    • -
-

Business Verification

- -

Business verification is a process that allows us to verify your identity as a business entity, which we require if your app will access sensitive data. Learn more about the Business Verification process.

-

Learn More

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - -
- - - - - - diff --git a/temp_fb_get_started.html b/temp_fb_get_started.html deleted file mode 100644 index 7eddf3e..0000000 --- a/temp_fb_get_started.html +++ /dev/null @@ -1,49 +0,0 @@ - - -Get Started - Marketing API - Documentation - Meta for Developers - - - - - - - - - - - - - - - - - -
Marketing API

Get Started with the Marketing API

- -

To effectively utilize the Marketing API, users must follow some key steps to set up their environment and gain access to the API's features. This section outlines the prerequisites necessary for getting started.

-

Ad Account Requirements

-

To manage your ads through the Marketing API, you must have an active ad account. This account is crucial not only for running campaigns but also for managing billing settings and setting spending limits. An ad account allows you to track your advertising expenses, monitor performance, and optimize your campaigns effectively.

Finding Your Ad Account Number

-

Locating your ad account number can be done through the Meta Ads Manager.

    -
  1. Log into Facebook: Start by logging into your Facebook account that is associated with your business.
    2. -
  2. Access Ads Manager: Ads Manager can be found in the drop-down menu in the upper right corner of your Facebook homepage or business page.
    3. -
  3. Locate your ad account: In Ads Manager, click on the ad account Settings from the menu on the bottom left of the screen.
    4. -
  4. View ad account information: In the Settings screen, you will find your ad account number listed along with other details such as your billing information and spending limits.
    5. -
-

Meta Developer Account

-

See Register as a Meta Developer for more information.

Create an App

-

See Create an App for more information on setting up an app in the App Dashboard as well as app types and use cases.

Authorization and Authentication

- -

See Authorization for more information on verifying the users and apps that will be accessing the Marketing API and granting them permissions.

- -

See Authentication for more information on getting, extending, and renewing access tokens with the Marketing API.

-

Next Steps

- -
    -
  1. Create an Ad Campaign
    2. -
  2. Manage Ad Campaigns
    3. -
  3. Optimize Ad Campaigns
    4. -
-
- - - diff --git a/temp_fb_insights_async.html b/temp_fb_insights_async.html deleted file mode 100644 index 73c20b0..0000000 --- a/temp_fb_insights_async.html +++ /dev/null @@ -1,303 +0,0 @@ - - -Limits & Best Practices - Marketing API - Documentation - Meta for Developers - - - - - - - - - - - - - - -
Marketing API

Limits and Best Practices

-

Beginning June 10, 2025, to improve overall API performance, reach will no longer be returned for standard queries that apply breakdowns and use start_dates more than 13 months old. (Responses to such requests will omit reach and related fields, such as frequency and cpp.)

- -

To apply breakdowns and still retrieve >13-month-old reach values, you can use asynchronous jobs to make up to 10 requests per Ad Account per day. Check the x-Fb-Ads-Insights-Reach-Throttle header to monitor how close you are to that rate-limit, and note that once the rate-limit is breached, requests will omit reach and related fields.

- -

When the rate limit threshold for reach-related breakdowns is exceeded, the following error message will be returned:

-
 Reach-related metric breakdowns are unavailable due to rate limit threshold.

Facebook Insights API provides performance data from Facebook marketing campaigns. To protect system performance and stability, we have protective measures to equally distribute system resources among applications. All policies we describe below are subject to change.

-

Timeouts

- -

The most common issue causing failure for Ads Insights API calls is too many requests and time outs.

- -
    -
  • /GET or synchronous requests can return out-of-memory or timeout errors.
    • -
  • /POST or asynchronous requests can return timeout errors. For asynchronous requests, it can take up to an hour to complete a request including retry attempts. For example, if you make a query that tries to fetch a large volume of data for many ad level objects.
    • -
- -

Recommendations

- -
    -
  • There is no explicit limit for when a query will fail. When it times out, try to break down the query into smaller queries by using filters like date range.
    • -
  • Unique metrics are time consuming to compute. Try to query unique metrics in a separate call to improve performance of non-unique metrics.
    • -
-

Data Per Call Limits

- -

We use data-per-call limits to prevent a query from retrieving too much data beyond what the system can handle. There are 2 types of data limits:

- -
    -
  1. By number of rows in response, and
    2. -
  2. By number of data points required to compute the total, such as summary row.
    3. -
- -

These limits apply to both sync and async /insights calls, and we return an error:

-
error_code = 100,  CodeException (error subcode: 1487534)

Best Practices, Data Per Call Limits

- -
    -
  • Limit your query by limiting the date range or number of ad ids. You can also limit your query to metrics that are necessary, or break it down into multiple queries with each requesting a subset of metrics.
    • -
  • Avoid account-level queries that include high cardinality breakdowns such as action_target_id or product_id, and wider date ranges like lifetime.
    • -
  • Use /insights edge directly with lower level ad objects to retrieve granular data for that level. For example, first use the account-level query to fetch the list of lower-level object ids with level and filtering parameters. In this example, we fetch all campaigns that recorded some impressions:
    • -
-
-curl -G \
--d 'access_token=<ACCESS_TOKEN>' \
--d 'level=campaign' \
--d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0}]' \
-'https://graph.facebook.com/v2.7/act_<ACCOUNT_ID>/insights'
-
    -
  • We can then use /<campaign_id>/insights with each returned value to query and batch the insights requests for these campaigns in a single call:
    • -
-
-curl \
--F 'access_token=<ACCESS_TOKEN>' \
--F 'batch=[ \
-  { \
-    "method": "GET", \
-    "relative_url": "v25.0/<CAMPAIGN_ID_1>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
-  }, \
-  { \
-    "method": "GET", \
-    "relative_url": "v25.0/<CAMPAIGN_ID_2>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
-  }, \
-  { \
-    "method": "GET", \
-    "relative_url": "v25.0/<CAMPAIGN_ID_3>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
-  } \
-]' \
-'https://graph.facebook.com'
-
    -
  • Use filtering parameter only to retrieve insights for ad objects with data. The field value specified in filtering uses DOT notation to denote the fields under the object. Please note that filtering with STARTS_WITH and CONTAIN does not change the summary data. In this case, use the IN operator. See example of a filtering request:
    • -
-
curl -G \
--d 'access_token=<ACCESS_TOKEN>' \
--d 'level=ad' \
--d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0},]' \
-'https://graph.facebook.com/v25.0/act_<ACCOUNT_ID>/insights'
    -
  • Use date_preset if possible. Custom date ranges are less efficient to run in our system.
    • -
  • Use batch requests for multiple sync calls and async to query for large volume of data to avoid timeouts.
    • -
  • Try sync calls first and then use async calls in cases where sync calls timeout
    • -
  • Insights refresh every 15 minutes and do not change after 28 days of being reported
    • -
-

Insights Call Load Limits

- -

Ninety days from the release of v3.3 and effective for all public versions, we change the ad account level rate limit to better reflect the volume of API calls needed. We compute the rate limit quota on your Marketing API access tier and the business owning your app. see Access and Authentication. This change applies to all Ads Insights API endpoints: GET {adaccount_ID}/insights, GET {campaign_ID}/insights, GET {adset_ID}/insights, GET {ad_ID}/insights, POST {adaccount_ID}/insights, POST {campaign_ID}/insights, POST {adset_ID}/insights, POST {ad_ID}/insights.

- -

We use load limits for optimal reporting experience. We measure API calls for their rate as well as the resources they require. We allow a fixed load limit per application per second. When you exceed that limit, your requests fail.

- -

Check the x-fb-ads-insights-throttle HTTP header in every API response to know how close your app is to its limit as well as to estimate how heavy a particular query may be. Insights calls are also subject to the default ad account limits shown in the x-ad-account-usage HTTP header. More details can be found here Marketing API, Best Practices

- -

Once an app reaches its limit, the call gets an error response with error_code = 4, CodedException. You should stay well below your limit. If your app reaches its allowed limits, only a certain percentage of requests go through, depending on the query, and the rate.

- -

We apply rate limiting to each app sending synchronous and asynchronous /insights calls combined. The two main parameters limits are counted against are by application, and by ad account.

- -

Here's an example of the HTTP header with an application's accrued score as a percentage of the limits:

-
X-FB-Ads-Insights-Throttle: { "app_id_util_pct": 100, "acc_id_util_pct": 10, "ads_api_access_tier": "standard_access" }

The header "x-fb-ads-insights-throttle" is a JSON value containing these info:

- -
    -
  • app_id_util_pct — The percentage of allocated capacity for the associated app_id has consumed.
    • -
  • acc_id_util_pct — The percentage of allocated capacity for the associated ad account_id has consumed.
    • -
  • ads_api_access_tier — Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
    • -
- -

Global Rate Limits

- -

During periods of elevated global load to the /insights endpoint, the system can throttle requests to protect the backend. This can occur in rare cases when too many queries of high complexity (large time ranges, complex metrics, and/or high number of ad object IDs) are coming at the same time. This will manifest in an error that looks like this:

-
error_code = 4,  CodeException (error subcode: 1504022), error_title: Too many API requests

During these periods, it is advised to reduce calls, wait a short period, and query again.

- -

Rate Limits Best Practices

- -
    -
  • Sending several queries at once are more likely to trigger our rate limiting. Try to spread your /insights queries by pacing them with wait time in your job.
    • -
  • Use the rate information in the HTTP response header to moderate your calls. Add a back-off mechanism to slow down or pause your /insights queries when you come close to hitting 100% utility for your application, or for your ad account.
    • -
  • We report ad insights data in the ad account's timezone. To retrieve insights data for the associated ad account daily, consider the time of day using the account timezone. This helps pace queries throughout the day.
    • -
  • Check the ads_api_access_tier that allows you to access the Marketing API. By default, apps are in the development_access tier and standard_access enables lower rate limiting. To get a higher rate limit and get to the standard tier, you can apply for the "Advanced Access" to the Ads Management Standard Access feature.
    • -
-

Insights API Asynchronous Jobs

- -

Fetch stats on many objects and apply filtering and sorting; we made the asynchronous workflow simpler:

- -

1. Send a POST request to <AD_OBJECT>/insights endpoint, which responds with the id of an Ad Report Run.

-
-{
-  "report_run_id": 6023920149050,
-}
-

Do not store the report_run_id for long term use, it expires after 30 days.

- -

2. Ad Report Runs contain information about this asynchronous job, such as async_status. Poll this field until async_status is Job Completed and async_percent_completion is 100.

-
-{
-  "id": "6044775548468",
-  "account_id": "1010035716096012",
-  "time_ref": 1459788928,
-  "time_completed": 1459788990,
-  "async_status": "Job Completed",
-  "async_percent_completion": 100
-}
-

Note: Beginning with Marketing API v25.0, if the report fails, you will see the corresponding error_code, error_message, error_subcode, error_user_title, and error_user_msg fields returned by default. See the Ads Insights Error Codes for more details on the returned error codes.

- -

3. Then you can query <AD_REPORT_RUN_ID>/insights edge to fetch the final result.

-
-{
-  "data": [
-    {
-      "impressions": "9708",
-      "date_start": "2009-03-28",
-      "date_stop": "2016-04-04"
-    },
-    {
-      "impressions": "18841",
-      "date_start": "2009-03-28",
-      "date_stop": "2016-04-04"
-    }
-  ],
-  "paging": {
-    "cursors": {
-      "before": "MAZDZD",
-      "after": "MQZDZD"
-    }
-  }
-}
-

This job gets all stats for the account and returns an asynchronous job ID:

-
-curl \
-  -F 'level=campaign' \
-  -F 'access_token=<ACCESS_TOKEN>' \
-  https://graph.facebook.com/v25.0/<CAMPAIGN_ID>/insights
-curl -G \
-  -d 'access_token=<ACCESS_TOKEN>' \
-  https://graph.facebook.com/v25.0/1000002
-curl -G \
-  -d 'access_token=<ACCESS_TOKEN>' \
-  https://graph.facebook.com/v25.0/1000003/insights
-

Async Job Status

-
StatusDescription

Job Not Started

-

Job has not started yet.

-

Job Started

-

Job has been started, but is not yet running.

-

Job Running

-

Job has started running.

-

Job Completed

-

Job has successfully completed.

-

Job Failed

-

Job has failed. Review your query and try again.

-

Job Skipped

-

Job has expired and skipped. Please resubmit your job and try again.

-

Export Reports

- -

We provide a convenience endpoint for exporting <AD_REPORT_RUN_ID> to a localized human-readable format.

- -

Note: this endpoint is not part of our versioned Graph API and therefore does not conform to its breaking-change policy. Scripts and programs should not rely on the format of the result as it may change unexpectedly.

-
-  curl -G \
-  -d 'report_run_id=<AD_REPORT_RUN_ID>' \
-  -d 'name=myreport' \
-  -d 'format=xls' \
-'https://www.facebook.com/ads/ads_insights/export_report/'
-
NameDescription

name

-
string

Name of downloaded file

-

format

-
enum{csv,xls}

Format of file

-

report_run_id

-
integer

ID of report to run

-

access_token

-
string

Permissions granted by the logged-in user. Provide this to export reports for another user.

-

Discrepancy with Ads Manager

-

Beginning June 10, 2025, to reduce discrepancies with Meta Ads Manager, the use_unified_attribution_setting and action_report_time parameters will be disregarded and API responses will mimic Ads Manager settings:

- -
    -
  • Attributed values will be based on ad set level attribution settings (similar to use_unified_attribution_setting=true), and inline/on-ad actions will be included in 1d_click or 1d_view attribution window data. After this change, standalone inline attribution window data will no longer be returned.
    • -
  • Actions will be reported using action_report_time=mixed: on-Meta actions (e.g., Link Clicks) will use impression-based reporting time; whereas off-Meta actions (e.g., Web Purchases) will leverage conversion-based reporting time.
    • -
-

The default behavior of the API is different from the default behavior of Ads Manager. If you would like to observe the same behavior as in Ads Manager, set the use_unified_attribution_setting field to true.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - -
- - - - - - diff --git a/temp_fb_system_users.html b/temp_fb_system_users.html deleted file mode 100644 index 621e4bf..0000000 --- a/temp_fb_system_users.html +++ /dev/null @@ -1,125 +0,0 @@ - - -System Users - Business Management APIs - Documentation - Meta for Developers - - - - - - - - - - - - - -
Business Management APIs

System Users

- -

Make programatic, automated actions on ad objects or Pages, or do programmatic ads buying. System users represent servers or software making API calls to assets owned or managed by a Business Manager.

-

The easiest, quickest way to create a system user is in the Business Manager tool. See Ads Help Center: How do I add a new System User.

-

To take actions for a person managing an ad account, you should take them through the standard Facebook oAuth flow and get a user access token. If you try to use system user tokens to work on ad objects or Pages on behalf of a real user of your software, you cannot link this user to those actions unless you take them through Facebook Login.

-

Documentation Contents

-

Overview

- -

Learn about the two different types of system users: admin system user and system user. Read API limits for system users.

- -

Guide: Create System Users

- -

Create, retrieve, and update a system user. Learn how to invalidate access tokens.

- -

Guide: Install Apps and Generate Tokens

- -

A guide to install apps and generate access tokens through your system user.

-

Guide: Permissions

- -

Assign system user tasks on ad accounts, user page, and proxied assets. Retrieve permissions.

- -

Guide: API Calls

- -

How to make automated API calls for Marketing API and Pages API.

- -

System Users And Custom Audiences

- -

Rules for system users to operate with a Custom File Custom Audience.

-

Resources

- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - -
- - - - - -