Справочник Python SDK для Meta Marketing API

Создаёт клиент из переменных окружения: FACEBOOK_APP_SECRET (для appsecret_proof) и META_GRAPH_VERSION. Дополнительные аргументы (timeout, retry, session, license_key) передаются в конструктор.

Ads.from_env(**kwargs) -> Ads

• ▸В отличие от других клиентов, пустой ключ не вызывает ошибку: без FACEBOOK_APP_SECRET поле app_secret останется пустым и appsecret_proof к запросам добавляться не будет. Если в настройках приложения Meta секрет обязателен, такие запросы будут отклонены.
• ▸Без META_GRAPH_VERSION используется версия SDK по умолчанию; нужную можно передать сразу: Ads.from_env(graph_version="...").
• ▸Access token отсюда не читается — он передаётся аргументом в каждый метод.

Возвращает рекламные кабинеты, доступные токену пользователя, списком AdAccount с id, name, currency и статусом. Обычно это первый вызов: большинству методов нужен ad_account_id.

await ads.ad_accounts(token: str) -> list[socialift.ads.AdAccount]

• ▸Нужны пользовательский access token (не токен страницы) и ads_read.
• ▸Возвращается одна страница — до 50 кабинетов.
• ▸is_active равен True, когда account_status в Meta равен 1.
• ▸Бюджеты — в валюте кабинета (currency); UZS нет в списке валют рекламных кабинетов Meta.

Нужные разрешения:ads_read

for account in await ads.ad_accounts(user_token):
    print(account.id, account.currency)

Возвращает пиксели Meta, подключённые к рекламному кабинету, с last_fired_time. ID пикселя нужен для групп объявлений на конверсии (promoted_object) и аудиторий сайта.

await ads.pixels(token: str, *, ad_account_id: str) -> list[dict]

• ▸Одна страница, до 50 пикселей; нужен ads_read.

Нужные разрешения:ads_read

pixels = await ads.pixels(user_token, ad_account_id="act_123")

Собирает спецификацию таргетинга Meta (dict) из простых аргументов: география, возраст, пол, языки, интересы, поведение, пользовательские аудитории, плейсменты. Чистая функция: без сетевых запросов и без токена.

Ads.build_targeting(
    *,
    countries: Optional[list[str]] = None,
    regions: Optional[list[Any]] = None,
    cities: Optional[list[Any]] = None,
    zips: Optional[list[Any]] = None,
    excluded_countries: Optional[list[str]] = None,
    excluded_cities: Optional[list[Any]] = None,
    age_min: Optional[int] = None,
    age_max: Optional[int] = None,
    genders: Optional[list[Any]] = None,
    locales: Optional[list[int]] = None,
    interests: Optional[list[Any]] = None,
    behaviors: Optional[list[Any]] = None,
    demographics: Optional[list[Any]] = None,
    life_events: Optional[list[Any]] = None,
    excluded_interests: Optional[list[Any]] = None,
    custom_audiences: Optional[list[str]] = None,
    excluded_custom_audiences: Optional[list[str]] = None,
    platforms: Optional[list[str]] = None,
    facebook_positions: Optional[list[str]] = None,
    instagram_positions: Optional[list[str]] = None,
    devices: Optional[list[str]] = None,
    connections: Optional[list[str]] = None,
    excluded_connections: Optional[list[str]] = None,
    flexible_spec: Optional[list[dict]] = None,
    advantage_audience: bool = True,
) -> dict[str, Any]

• ▸Элементы внутри interests объединяются через ИЛИ; для «И» используйте flexible_spec — каждый его элемент является отдельным условием И.
• ▸genders принимает 1/2 или "male"/"female"; чтобы охватить всех, не передавайте его вовсе. Возраст приводится к диапазону 13–65.
• ▸advantage_audience по умолчанию True. При включённой Advantage+ audience Meta фиксирует age_max на 65 и принимает age_min только от 18 до 25 — для жёстких возрастных рамок передайте advantage_audience=False.
• ▸Meta требует географию в таргетинге группы объявлений; хелпер это не проверяет, поэтому передайте countries, regions, cities или zips.

targeting = ads.build_targeting(countries=["UZ"], age_min=18, age_max=45, interests=[{"id": "6003107902433"}], advantage_audience=False)

Оценивает размер аудитории для спецификации таргетинга и цели оптимизации, ничего не создавая и не тратя деньги. Чтобы до создания группы объявлений поймать слишком маленькую или слишком широкую аудиторию.

await ads.delivery_estimate(
    token: str,
    *,
    ad_account_id: str,
    targeting: dict[str, Any],
    optimization_goal: str = 'REACH',
    promoted_object: Optional[dict] = None,
) -> dict

• ▸Только чтение: ничего не создаётся и ничего не списывается.
• ▸Возвращает первую строку оценки из ответа Meta как dict (или пустой dict).
• ▸optimization_goal по умолчанию REACH; укажите цель, которую планируете для группы объявлений.
• ▸Нужен ads_read.

Нужные разрешения:ads_read

estimate = await ads.delivery_estimate(user_token, ad_account_id="act_123", targeting=targeting)

Ищет варианты таргетинга по интересам Meta по названию: возвращает id, name, границы размера аудитории и path. Используйте ID в build_targeting(interests=...).

await ads.search_interests(token: str, query: str, *, limit: int = 25) -> list[dict]

• ▸limit по умолчанию 25; нужен ads_read.
• ▸Meta со временем выводит интересы из использования — проверяйте сохранённые ID через validate_targeting().

Нужные разрешения:ads_read

interests = await ads.search_interests(user_token, "fitness", limit=25)
cities = await ads.search_locations(user_token, "Tosh", country_code="UZ")

Ищет варианты таргетинга Meta по языку (locale) и возвращает числовые ключи для build_targeting(locales=...). Используйте, когда аудиторию нужно разделить по языку, а не по географии.

await ads.search_locales(token: str, query: str, *, limit: int = 25) -> list[dict]

Ищет локации Meta (страны, регионы, города) по названию; key из ответа — идентификатор, который ждёт таргетинг. Сужайте выдачу через country_code.

await ads.search_locations(
    token: str,
    query: str,
    *,
    location_types: tuple[str, ...] = ('city', 'region', 'country'),
    country_code: Optional[str] = None,
    limit: int = 25,
) -> list[dict]

• ▸location_types по умолчанию: city, region, country; для почтовых индексов добавьте zip.
• ▸Городу можно задать радиус: {"key": "...", "radius": 25, "distance_unit": "kilometer"}; Meta принимает 17–80 км (10–50 миль).
• ▸Нужен ads_read.

Нужные разрешения:ads_read

interests = await ads.search_interests(user_token, "fitness", limit=25)
cities = await ads.search_locations(user_token, "Tosh", country_code="UZ")

Перечисляет или ищет категории таргетинга одного класса: behaviors, demographics, life_events, industries, income и другие. Без query возвращается весь класс — например, чтобы построить список для выбора.

await ads.search_targeting(
    token: str,
    *,
    target_class: str = 'interests',
    query: Optional[str] = None,
    limit: int = 50,
) -> list[dict]

• ▸target_class должен быть из TARGETING_CLASSES, иначе ещё до запроса выбрасывается ConfigurationError.

Предлагает варианты таргетинга, похожие на переданные (например, близкие интересы). Быстрый способ расширить слишком узкую аудиторию.

await ads.targeting_suggestions(
    token: str,
    *,
    ad_account_id: str,
    targeting_list: list[dict],
    limit: int = 25,
) -> list[dict]

• ▸Формат targeting_list: [{"type": "interests", "id": "..."}]; нужен ads_read.

Нужные разрешения:ads_read

similar = await ads.targeting_suggestions(user_token, ad_account_id="act_123", targeting_list=[{"type": "interests", "id": "6003107902433"}])

Проверяет, действительны ли ещё сохранённые элементы таргетинга (ID интересов и т. п.) для этого кабинета. Вызывайте перед повторным использованием старого таргетинга в новой группе объявлений.

await ads.validate_targeting(
    token: str,
    *,
    ad_account_id: str,
    targeting_list: list[dict],
) -> list[dict]

• ▸Meta со временем выводит варианты таргетинга из использования, поэтому ID, сохранённые месяцы назад, могут перестать работать.
• ▸Нужен ads_read.

Нужные разрешения:ads_read

result = await ads.validate_targeting(user_token, ad_account_id="act_123", targeting_list=[{"type": "interests", "id": "6003107902433"}])

Возвращает объявления с креативом, статусом и ссылкой на предпросмотр — по одной группе объявлений, одной кампании или всему кабинету.

await ads.ads(
    token: str,
    *,
    ad_account_id: Optional[str] = None,
    adset_id: Optional[str] = None,
    campaign_id: Optional[str] = None,
    limit: int = 100,
) -> list[dict]

• ▸Приоритет: adset_id, затем campaign_id, затем ad_account_id; если нет ни одного — ConfigurationError.
• ▸Одна страница до limit элементов; нужен ads_read.

Нужные разрешения:ads_read

items = await ads.ads(user_token, adset_id="120200000000001")

Получает одну группу объявлений по ID с таргетингом, бюджетами, ставкой, целью оптимизации и расписанием.

await ads.adset(token: str, adset_id: str) -> dict

Возвращает группы объявлений кампании (campaign_id) или всего рекламного кабинета (ad_account_id) с полями таргетинга, бюджета и оптимизации.

await ads.adsets(
    token: str,
    *,
    ad_account_id: Optional[str] = None,
    campaign_id: Optional[str] = None,
    limit: int = 100,
) -> list[dict]

• ▸Если переданы оба, приоритет у campaign_id; если ни одного — ConfigurationError.
• ▸Одна страница до limit (по умолчанию 100) элементов; нужен ads_read.

Нужные разрешения:ads_read

adsets = await ads.adsets(user_token, campaign_id="120200000000000")

Превращает существующий пост Instagram в рекламу за один вызов: создаёт кампанию, группу объявлений, креатив из поста и объявление — всё в PAUSED. Возвращает их ID; деньги не тратятся, пока не вызван set_status(..., "ACTIVE").

await ads.boost_post(
    token: str,
    *,
    ad_account_id: str,
    ig_user_id: str,
    media_id: str,
    name: str,
    daily_budget_major: float,
    goal: str = 'traffic',
    page_id: Optional[str] = None,
    link: Optional[str] = None,
    targeting: Optional[dict[str, Any]] = None,
    currency: Optional[str] = None,
    cleanup_on_error: bool = True,
) -> dict[str, str]

• ▸goal: traffic, engagement, reach или messages (сопоставляется с целью OUTCOME_* и оптимизацией); для messages обязателен page_id. Кампания создаётся с пустым special_ad_categories — не используйте метод для рекламы жилья, вакансий, финансов или политики.
• ▸daily_budget_major — в валюте кабинета, умножается на CURRENCY_OFFSET (100); для валют с offset 1 в Meta (JPY, KRW, IDR, VND, HUF …) сначала разделите сумму на 100.
• ▸Без targeting используется default_targeting(): UZ, возраст 18–55, плейсменты Instagram, Advantage+ audience включена.
• ▸Четыре объекта создаются по очереди: если следующий шаг падает, предыдущие остаются в кабинете (PAUSED) — удалите их. Посты с музыкой, защищённой авторским правом, или интерактивными элементами вроде фильтров продвигать нельзя.

Нужные разрешения:ads_managementinstagram_basic

result = await ads.boost_post(user_token, ad_account_id="act_123", ig_user_id="1784...", media_id="1790...", name="Reels boost", daily_budget_major=10, goal="traffic")

Получает одну кампанию по ID с теми же полями, что и campaigns(): цель, статус, бюджеты, стратегия ставок, особые категории рекламы.

await ads.campaign(token: str, campaign_id: str) -> dict

Возвращает кампании рекламного кабинета с полями бюджета, цели и статуса. Фильтруйте через statuses, например ["ACTIVE", "PAUSED"].

await ads.campaigns(
    token: str,
    *,
    ad_account_id: str,
    statuses: Optional[list[str]] = None,
    limit: int = 100,
) -> list[dict]

• ▸statuses отправляется в Meta как фильтр effective_status.
• ▸Возвращается одна страница до limit (по умолчанию 100) элементов, без автопагинации.
• ▸Нужен ads_read.

Нужные разрешения:ads_read

campaigns = await ads.campaigns(user_token, ad_account_id="act_123", statuses=["ACTIVE", "PAUSED"])

Создаёт объявление в группе из готового creative_id или встроенной спецификации creative. По умолчанию в PAUSED.

await ads.create_ad(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    adset_id: str,
    creative_id: Optional[str] = None,
    creative: Optional[dict] = None,
    status: str = 'PAUSED',
    **extra: Any,
) -> dict

• ▸Нужен creative_id или creative; если переданы оба, используется creative_id.
• ▸Дополнительные поля Meta передаются через **extra строками или числами (dict сериализуйте в JSON сами).

Нужные разрешения:ads_management

ad = await ads.create_ad(user_token, ad_account_id="act_123", name="Banner A", adset_id="120200000000001", creative_id="120200000000002")

Создаёт группу объявлений: кто видит рекламу (таргетинг), как идёт оптимизация и — если у кампании нет бюджета — сколько тратится. По умолчанию создаётся в PAUSED.

await ads.create_adset(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    campaign_id: str,
    targeting: dict[str, Any],
    optimization_goal: str = 'LINK_CLICKS',
    billing_event: str = 'IMPRESSIONS',
    status: str = 'PAUSED',
    daily_budget_major: Optional[float] = None,
    lifetime_budget_major: Optional[float] = None,
    bid_amount_major: Optional[float] = None,
    start_time: Optional[str] = None,
    end_time: Optional[str] = None,
    promoted_object: Optional[dict] = None,
    destination_type: Optional[str] = None,
    currency: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸targeting не может быть пустым — собирайте его через build_targeting() или default_targeting(). optimization_goal и billing_event проверяются по OPTIMIZATION_GOALS и BILLING_EVENTS.
• ▸daily_budget_major, lifetime_budget_major и bid_amount_major умножаются на CURRENCY_OFFSET (100); для валют с offset 1 (JPY, KRW, IDR, VND, HUF …) сначала разделите на 100.
• ▸С lifetime_budget_major обязателен end_time. При создании Meta принимает только статус ACTIVE или PAUSED.
• ▸Для некоторых целей нужен promoted_object, например {"pixel_id": "...", "custom_event_type": "PURCHASE"} для конверсий.

Нужные разрешения:ads_management

adset = await ads.create_adset(user_token, ad_account_id="act_123", name="Toshkent 18-45", campaign_id="120200000000000", targeting=targeting, daily_budget_major=15)

Создаёт кампанию — верхний уровень, который задаёт цель и, при необходимости, бюджет кампании. По умолчанию создаётся в PAUSED.

await ads.create_campaign(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    objective: str = 'OUTCOME_TRAFFIC',
    status: str = 'PAUSED',
    daily_budget_major: Optional[float] = None,
    lifetime_budget_major: Optional[float] = None,
    bid_strategy: Optional[str] = None,
    special_ad_categories: Optional[list[str]] = None,
    special_ad_category_country: Optional[list[str]] = None,
    is_adset_budget_sharing_enabled: Optional[bool] = None,
    currency: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸objective должен быть одним из значений OUTCOME_* из OBJECTIVES; старые названия дают ConfigurationError.
• ▸special_ad_categories отправляется всегда (по умолчанию пустой список): Meta требует от каждой кампании указать категорию, например HOUSING, EMPLOYMENT, FINANCIAL_PRODUCTS_SERVICES, ISSUES_ELECTIONS_POLITICS.
• ▸Бюджет задаётся либо здесь (daily_budget_major или lifetime_budget_major, что-то одно), либо в группах объявлений, но не там и там. Сумма умножается на CURRENCY_OFFSET (100) — для валют с offset 1, таких как JPY и KRW, сначала разделите на 100.
• ▸Начиная с Marketing API v24.0 кампания без собственного бюджета требует is_adset_budget_sharing_enabled; передайте его через **extra строкой ("false" или "true").

Нужные разрешения:ads_management

campaign = await ads.create_campaign(user_token, ad_account_id="act_123", name="Kuz aksiyasi", objective="OUTCOME_TRAFFIC", daily_budget_major=20)

Удаляет кампанию, группу объявлений, объявление или другой объект Marketing API по ID HTTP-запросом DELETE. Чтобы остановить расход, но сохранить объект, используйте set_status(..., "PAUSED").

await ads.delete(token: str, node_id: str) -> bool

• ▸Возвращает флаг success от Meta; нужен ads_management.

Нужные разрешения:ads_management

await ads.delete(user_token, node_id)

Меняет статус кампании, группы объявлений или объявления. ACTIVE запускает расход; PAUSED останавливает показы и является безопасным способом выключить рекламу.

await ads.set_status(token: str, node_id: str, status: str) -> bool

• ▸Допустимые значения: ACTIVE, PAUSED, ARCHIVED, DELETED; любое другое — ConfigurationError.
• ▸Если кампания или группа на паузе, эффективный статус объявлений в ней — CAMPAIGN_PAUSED или ADSET_PAUSED.
• ▸Нужен ads_management.

Нужные разрешения:ads_management

await ads.set_status(user_token, campaign_id, "ACTIVE")

Устанавливает группе объявлений новый дневной бюджет. Влияет на уже работающую рекламу, поэтому перепроверьте сумму.

await ads.update_budget(
    token: str,
    adset_id: str,
    daily_budget_major: float,
    *,
    currency: Optional[str] = None,
    ad_account_id: Optional[str] = None,
) -> bool

• ▸daily_budget_major должен быть больше нуля и умножается на CURRENCY_OFFSET (100); для валют с offset 1 сначала разделите на 100.
• ▸Нужен ads_management.

Нужные разрешения:ads_management

await ads.update_budget(user_token, adset_id, daily_budget_major=25)

Заменяет таргетинг существующей группы объявлений переданной спецификацией. Передавайте полную новую спецификацию, а не только изменения.

await ads.update_targeting(token: str, adset_id: str, targeting: dict[str, Any]) -> bool

• ▸Пустой targeting даёт ConfigurationError; нужен ads_management.
• ▸Возрастные правила Advantage+ audience действуют и здесь (см. build_targeting()).

Нужные разрешения:ads_management

await ads.update_targeting(user_token, adset_id, targeting)

Создаёт креатив объявления со ссылкой из страницы, URL, текста и загруженного изображения (image_hash) или видео (video_id). Используйте, когда нужен отдельный рекламный креатив, а не существующий пост (boost_post()).

await ads.create_creative(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    page_id: str,
    link: str,
    message: Optional[str] = None,
    headline: Optional[str] = None,
    description: Optional[str] = None,
    image_hash: Optional[str] = None,
    video_id: Optional[str] = None,
    call_to_action: str = 'LEARN_MORE',
    instagram_user_id: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸SDK собирает object_story_spec.link_data: headline попадает в name, call_to_action (по умолчанию LEARN_MORE) — в type.
• ▸Чтобы объявление показывалось от имени аккаунта Instagram, передайте instagram_user_id; page_id обязателен всегда.
• ▸image_hash берите из upload_image(). Нужен ads_management.

Нужные разрешения:ads_management

creative = await ads.create_creative(user_token, ad_account_id="act_123", name="Kuz", page_id="1111", link="https://siz.uz", message="Chegirma 30%", image_hash=image_hash)

Возвращает HTML (iframe в body), показывающий, как объявление будет выглядеть в выбранном плейсменте. Чтобы показать его человеку перед запуском.

await ads.preview(
    token: str,
    ad_id: str,
    *,
    ad_format: str = 'MOBILE_FEED_STANDARD',
) -> list[dict]

• ▸ad_format по умолчанию MOBILE_FEED_STANDARD; DESKTOP_FEED_STANDARD и другие форматы описаны в документации Meta по предпросмотру.
• ▸Нужен ads_read.

Нужные разрешения:ads_read

previews = await ads.preview(user_token, ad_id, ad_format="INSTAGRAM_STANDARD")

Загружает байты изображения в библиотеку изображений рекламного кабинета и возвращает {"hash", "url", "raw"}. Креативы ссылаются на изображение именно по этому hash.

await ads.upload_image(
    token: str,
    *,
    ad_account_id: str,
    image: bytes,
    filename: str = 'ad.jpg',
) -> dict

• ▸image — сырые bytes, а не путь; filename — только имя файла при загрузке.
• ▸Нужен ads_management.

Нужные разрешения:ads_management

with open("banner.jpg", "rb") as f:
    image = await ads.upload_image(user_token, ad_account_id="act_123", image=f.read(), filename="banner.jpg")

Добавляет людей в аудиторию-список клиентов по email и/или телефону. Значения нормализуются и хешируются SHA-256 на вашем сервере — открытые контактные данные его не покидают.

await ads.add_audience_users(
    token: str,
    audience_id: str,
    *,
    emails: Optional[list[str]] = None,
    phones: Optional[list[str]] = None,
    phone_country: Optional[str] = None,
    batch_size: int = 10000,
) -> dict

• ▸Нормализация: email очищается от пробелов и приводится к нижнему регистру; в телефоне остаются только цифры. Ведущие нули не удаляются, код страны не добавляется — передавайте номер в международном формате, например +998901234567.
• ▸Meta принимает до 10 000 записей за запрос; большие списки делите на несколько вызовов.
• ▸Если переданы оба списка, они склеиваются построчно как один человек: длина и порядок должны совпадать (лишние элементы отбрасываются).
• ▸Нужен ads_management.

Нужные разрешения:ads_management

await ads.add_audience_users(user_token, audience_id, emails=["ali@example.com"], phones=["+998901234567"])

Создаёт пустую пользовательскую аудиторию — по умолчанию список клиентов (subtype="CUSTOM"), который затем заполняется через add_audience_users().

await ads.create_custom_audience(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    subtype: str = 'CUSTOM',
    description: Optional[str] = None,
    customer_file_source: str = 'USER_PROVIDED_ONLY',
    rule: Optional[dict] = None,
    **extra: Any,
) -> dict

• ▸Для списка клиентов кабинет должен принять условия Custom Audience Terms Meta, иначе Meta вернёт ошибку о непринятых условиях.
• ▸customer_file_source указывает источник данных: USER_PROVIDED_ONLY (по умолчанию), PARTNER_PROVIDED_ONLY или BOTH_USER_AND_PARTNER_PROVIDED.
• ▸rule отправляется в JSON; прочие поля Meta — через **extra. Нужен ads_management.

Нужные разрешения:ads_management

audience = await ads.create_custom_audience(user_token, ad_account_id="act_123", name="Mijozlar")

Создаёт похожую (lookalike) аудиторию в одной стране на основе исходной. Чем меньше ratio, тем выше сходство и тем меньше аудитория.

await ads.create_lookalike(
    token: str,
    *,
    ad_account_id: str,
    name: str,
    origin_audience_id: str,
    country: str = 'UZ',
    ratio: float = 0.01,
) -> dict

• ▸ratio — от 0.01 до 0.20 (самые похожие 1–20% страны); по умолчанию 0.01, country по умолчанию UZ.
• ▸В исходной аудитории должно быть не меньше 100 человек из одной страны.
• ▸Заполнение lookalike занимает 1–6 часов; группы объявлений с ней можно создавать уже в это время.
• ▸Нужен ads_management.

Нужные разрешения:ads_management

lookalike = await ads.create_lookalike(user_token, ad_account_id="act_123", name="1% UZ", origin_audience_id="1202...", country="UZ", ratio=0.01)

Возвращает пользовательские аудитории кабинета с типом (subtype), примерными границами размера и статусами доставки и обработки.

await ads.custom_audiences(
    token: str,
    *,
    ad_account_id: str,
    limit: int = 100,
) -> list[dict]

• ▸Одна страница до limit (по умолчанию 100) элементов; нужен ads_read.

Нужные разрешения:ads_read

custom = await ads.custom_audiences(user_token, ad_account_id="act_123")
saved = await ads.saved_audiences(user_token, ad_account_id="act_123")

Возвращает сохранённые в Ads Manager аудитории (шаблоны таргетинга) со спецификацией таргетинга и примерным размером.

await ads.saved_audiences(
    token: str,
    *,
    ad_account_id: str,
    limit: int = 100,
) -> list[dict]

• ▸Одна страница до limit элементов; нужен ads_read.

Нужные разрешения:ads_read

custom = await ads.custom_audiences(user_token, ad_account_id="act_123")
saved = await ads.saved_audiences(user_token, ad_account_id="act_123")

Возвращает расходы и результаты по кампании, группе объявлений, объявлению или кабинету как AdInsights (spend, impressions, reach, clicks, link_clicks, cpc, ctr, frequency). Для быстрой карточки с итогами.

await ads.insights(
    token: str,
    node_id: str,
    *,
    since: Optional[str] = None,
    until: Optional[str] = None,
) -> socialift.ads.AdInsights

• ▸Передавайте и since, и until (YYYY-MM-DD); иначе берётся весь период (date_preset=maximum).
• ▸Читается только первая строка; для разрезов используйте insights_rows().
• ▸Нужен ads_read.

Возвращает сырые строки статистики на выбранном level с необязательными breakdowns (age, gender, country, publisher_platform и т. п.). Чтобы найти сегмент, где результат дешевле.

await ads.insights_rows(
    token: str,
    node_id: str,
    *,
    level: str = 'campaign',
    date_preset: Optional[str] = 'last_30d',
    since: Optional[str] = None,
    until: Optional[str] = None,
    breakdowns: Optional[list[str]] = None,
    action_breakdowns: Optional[list[str]] = None,
    fields: Optional[str] = None,
    limit: int = 200,
) -> list[dict]

• ▸Meta поддерживает только часть комбинаций разрезов: age + gender работает, age + country — нет.
• ▸Если переданы since + until, они используются вместо date_preset (по умолчанию last_30d).
• ▸Одна страница до limit (по умолчанию 200) строк; нужен ads_read.

Нужные разрешения:ads_read

rows = await ads.insights_rows(user_token, "act_123", level="campaign", date_preset="last_7d", breakdowns=["age", "gender"])

Вызывает любой путь Marketing API с подписью SDK (access_token, appsecret_proof), повторами и классификацией ошибок. Для эндпоинтов без обёртки, например правил автоматизации.

await ads.call(token: str, path: str, *, method: str = 'GET', **params: Any) -> Any

• ▸Порядок аргументов — token, path; method по умолчанию GET. Всё, кроме GET/DELETE, отправляется как POST и меняет реальные объекты.
• ▸Значения dict/list сериализуются в JSON автоматически; булевы значения передавайте строками ("true"/"false").

Нужные разрешения:ads_read

data = await ads.call(user_token, "act_123/adcreatives", method="GET", fields="id,name")

Отправляет произвольный HTTP-запрос и возвращает JSON-ответ — для эндпоинта, у которого в SDK пока нет отдельного метода. Токен и параметры подписи (access_token, для Meta — appsecret_proof через socialift.crypto.appsecret_proof) вы передаёте сами в params или headers.

await ads.request(
    method: str,
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    data: Optional[Any] = None,
    json: Optional[Any] = None,
    headers: Optional[Mapping[str, str]] = None,
) -> Any

• ▸Значения None в params не отправляются.
• ▸При лимите (RateLimitError) и временных ошибках сервера (HTTP 429, 500, 502, 503, 504) запрос повторяется по RetryPolicy; если есть заголовок Retry-After, SDK ждёт указанное время. Обрыв сети выбрасывается как TransportError.

Короткая форма request("GET", ...).

await ads.get(url: str, **kw) -> Any

Короткая форма request("POST", ...).

await ads.post(url: str, **kw) -> Any

Короткая форма request("DELETE", ...).

await ads.delete(url: str, **kw) -> Any

Проходит по курсорной пагинации Meta (paging.next) и возвращает все элементы data одним списком.

await ads.paginate(
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    max_items: int = 500,
    page_size: int = 100,
) -> list[dict]

• ▸max_items (по умолчанию 500) — защитный предел: у крупного аккаунта могут быть десятки тысяч записей. page_size — limit одного запроса.

Закрывает HTTP-сессию, созданную самим SDK (переданную извне сессию не трогает). При использовании async with Client(...) вызывается автоматически.

await ads.close() -> None