| Version | Pfad | Einführungsdatum | Datum der Außerdienststellung | End-of-Life-Datum |
|---|---|---|---|---|
| 12.0 | /12/ | 27. Oktober 2022 | wird noch bekannt gegeben | wird noch bekannt gegeben |
| 11.0 | /11/ | 31. März 2022 | wird noch bekannt gegeben | wird noch bekannt gegeben |
| 10.0 | /10/ | 31. August 2021 | 31. März 2022 | 27. Oktober 2022 |
| 9.0 | /9/ | 2. März 2021 | 31. August 2021 | 31. März 2022 |
| 8.0 | /8/ | 8. September 2020 | 2. März 2021 | 31. August 2021 |
| 7.0 | /7/ | 3. März 2020 | 1. September 2020 | 2. März 2021 |
| 6.0 | /6/ | 28. August 2019 | 3. März 2020 | 1. September 2020 |
| 5.0 | /5/ | 28. Februar 2019 | 28. August 2019 | 3. März 2020 |
| 4.0 | /4/ | 28. August 2018 | 28. Februar 2019 | 28. August 2019 |
| 3.0 | /3/ | 1. Februar 2018 | 28. August 2018 | 28. Februar 2019 |
| 2.0 | /2/ | 10. Juli 2017 | 1. Februar 2018 | 1. August 2018 |
| 1.0 | /1/ | 31. März 2016 | 7. Juli 2017 | 10. Januar 2018 |
| 0.0 | /0/ | 21. Februar 2013 | k. A. | 31. Oktober 2016 |
Überblick
- Entfernen eines Params aus der API‑Anfrage/-Antwort
- Ändern des Namens eines beliebigen Params oder endpoints
- Änderung in der Darstellung von Werten (preview_url → card_uri)
- Verhaltensänderung von endpoints (z. B. asynchron vs. synchron bei Statistiken)
- Hinzufügen/Ändern optionaler oder erforderlicher Params (z. B. name als Pflichtfeld in der Anfrage festlegen)
Versionierungsstrategie
- Alle Breaking Changes werden in einer neuen Version gebündelt.
- Die Auslaufphase für bestehende Versionen beträgt 6 Monate, sobald eine neue Version angekündigt wird.
- Zu jedem Zeitpunkt akzeptiert die API Anfragen aus zwei Versionen gleichzeitig; die ältere der beiden wird jedoch nicht unterstützt.
- Um eine schnellere Einführung neuer Produkte zu ermöglichen, werden diese fortlaufend (außerhalb des Versionsrhythmus) veröffentlicht.
-
Alle API-Antworten enthalten einen
x-current-api-version-Header, der auf die aktuelle Version der API gesetzt ist, sowie zusätzlich einenx-api-warn-Header beim Aufruf veralteter API-endpoints.
v9
Hinweis: Mit dieser Veröffentlichung hat Version 7 (v7) der Ads API das End-of-Life erreicht und ist nicht mehr verfügbar.
v8
v7
v6
v5
accounts/:account_id/account_media-endpoint als veraltet markiert.
Wie bei früheren Versionen wird es eine Übergangsphase von 6 Monaten für die Migration auf v5 geben. Am 2019-08-28 wird Version 4 der Ads API nicht mehr verfügbar sein. Wir empfehlen allen Partnern, so schnell wie möglich auf die neueste Version der API zu migrieren, um Serviceunterbrechungen zu vermeiden. Version 3 der Ads API hat das Ende ihres Lebenszyklus erreicht und ist nicht mehr verfügbar.
Neu
CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE und PROMOTED_TWEET.
MEDIA_CREATIVE-Statistiken
Die Analytics-Endpoints der Ads API stellen jetzt metrics für Media-Creative-Entities bereit. Media Creatives sind die Einheit, über die In-Stream-Anzeigen oder Bilder auf der X Audience Platform beworben werden. Die X Ads UI zeigt Media-Creative-metrics unter den Tabs „In-stream videos“ und „Display creatives“ an. Sowohl die synchronen als auch die asynchronen Analytics-Endpoints unterstützen jetzt das MEDIA_CREATIVE-Entity-Enum.
Mehrere Cards abrufen
Aufbauend auf dem v3-Release des Endpoints, der das Abrufen einer einzelnen Card anhand ihres Card-URI-Werts ermöglicht, ist es nun möglich, mehrere Cards über den Endpoint GET accounts/:account_id/cards/all abzurufen. Anstatt für jede Card eine separate Anfrage zu stellen, können Sie jetzt bis zu 200 Cards in einer einzigen Anfrage abrufen.
Zwei Dinge sind zu beachten:
- Der URL-Pfad lautet jetzt
accounts/:account_id/cards/all. (Der vorherige Pfad ist nicht mehr verfügbar.) Dies dient der Konsistenz mit dem Endpoint, der das Abrufen einer Card per ID ermöglicht. - Der erforderliche Anfrageparameter heißt jetzt card_uris (Plural).
- GET accounts/:account_id/line_item_apps
- GET accounts/:account_id/media_creatives
- GET accounts/:account_id/promoted_accounts
- GET accounts/:account_id/preroll_call_to_actions
Geändert
draft_only | with_draft | |
Targeting der Netzwerkaktivierungsdauer
Die Ads API hat ein Anzeigeproblem behoben, bei dem nach dem Hinzufügen des Targetings für die Netzwerkaktivierungsdauer der Targeting-Typ in der Antwort das Suffix _IN_SEC enthielt. Ein Verweis auf Sekunden war irreführend, da die Netzwerkaktivierungsdauer stets in Monaten angegeben wird. Diese Korrektur sorgt für eine konsistente Darstellung und reduziert Verwirrung.
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |
Gesamtanzahlen und Cursor
In v5 sind with_total_count und cursor gegenseitig exklusiv. Die Angabe beider in einer Anfrage führt zum Fehlercode EXCLUSIVE_PARAMETERS. Vor v5 wurde with_total_count ignoriert, wenn cursor angegeben war. Diese Änderung macht das Verhältnis explizit.
Entfernt
- In v4 wurde angekündigt, dass der response-Parameter preview_url für Cards stets null ist. Der letzte Schritt dieser Migration besteht darin, preview_url aus allen Cards-Antworten zu entfernen.
- Das response-Attribut account_id wird für die folgenden Ressourcen entfernt, da die Ads-Konto-ID bereits in der URL sowie in request.params vorhanden ist. (Es ist beabsichtigt, Funding Instruments aus dieser Liste auszuschließen, da Parent-IDs nach Möglichkeit in Response-Objekten vorhanden sein sollten und Account-IDs übergeordnete Entitäten zu Funding Instruments sind.)
- Account Media
- App Event Providers
- App Event Tags
- Campaigns
- Cards
- Line Items
- Promotable users
- Targeting criteria
- Für GET accounts/:account_id/targeting_criteria-Anfragen geben wir das Feld parent_ids nicht mehr zurück, da es stets ein leeres Array war.
- Hinweis: Dies betrifft nicht Bild- und Video-App-Download-Cards.
AMPLIFY_VIDEO-Assets, die zur Media Library hinzugefügt werden, werden automatisch als Account-Media-Asset mit dem Creative-TypPREROLLhinzugefügt.- Bilder mit bestimmten Abmessungen, die zur Media Library hinzugefügt werden, werden automatisch als Account-Media-Assets hinzugefügt. Der Creative-Typ (z. B.
INTERSTITIAL) hängt von den Bildabmessungen ab. (Für Abmessungen siehe unsere Seite Enumerations.)
v4
Neu
- TON Upload:
- GET accounts/:account_id/tailored_audience_changes
- GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
- POST accounts/:account_id/tailored_audience_changes
- PUT accounts/:accounti_d/tailored_audiences/global_opt_out
- Real Time Audiences:
- POST tailored_audience_memberships
list_type in Version 4 aus Anfrage und Antwort bei allen Tailored Audiences endpoints entfernt.
Settings Endpoints
Wir bieten nun Kontoadministratoren die Möglichkeit, Benutzer-, Konto- und Steuereinstellungen festzulegen und zu aktualisieren. User settings entsprechen den nutzerspezifischen Kontaktpräferenzen für ein bestimmtes Anzeigenkonto. Über das endpoint PUT accounts/:account_id können Werbetreibende jetzt ihren Kontonamen und die Branchenzuordnung aktualisieren. Schließlich ermöglichen die endpoints für tax settings Werbetreibenden in Ländern, in denen eine Mehrwertsteuer (VAT) erhoben wird, Angaben wie Firmenname, Adresse, USt-IdNr. (VAT ID) sowie ob das Konto dem Werbetreibenden gehört oder von einer Agentur im Auftrag eines Werbetreibenden verwaltet wird, zu aktualisieren.
Geändert
lookalike_expansion an den POST accounts/:account_id/line_items- und PUT accounts/:accountit/line_items/:line_item_id-Endpoints.
| v3 | v4 |
|---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code überall verwenden
Im Rahmen einer größeren Initiative zur Konsistenz in der Ads API benennen wir die Parameter an den folgenden Endpoints von app_country_code in country_code um.
- POST accounts/:account_id/cards/image_app_download
- PUT accounts/:account_id/cards/image_app_download/:card_id
- POST accounts/:account_id/cards/video_app_download
- PUT accounts/:account_id/cards/video_app_download/:card_id
preview_url immer null
Wie in der v3-Ankündigung versprochen, verfügen nun alle bestehenden Cards über eine card_uri. Daher ist der Wert von preview_url stets null.
Zur Erinnerung: Verknüpfen Sie eine Card mit einem Tweet, indem Sie deren card_uri-Wert verwenden. Siehe die folgende Beispielanfrage.
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
Entfernt
-
v3-Videos-Endpunkt:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos" -
v4-Media-Library-Endpunkt für Videos:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id in der Tweet-Ansicht
Der Parameter as_user_id, der am Endpunkt GET accounts/:account_id/tweet/preview/:tweet_id verfügbar war, wird nicht mehr akzeptiert. Die Vorschau wird stets als Autor des Tweets gerendert.
v3
- Für eine eingegebene Zielgruppe die relevantesten Hashtags, @handles und Events abrufen.
- Für eine eingegebene Zielgruppe wichtige demografische Informationen abrufen (z. B. Alter, Geschlecht und Haushaltseinkommen).
- Für ein Keyword die Zeitreihe des Tweet-Volumens abrufen
Weitere Änderungen
- Die Antwort des GET insights/keywords/search-Endpoints enthält jetzt ein related_keywords-Attribut mit 30 Begriffen, die mit den eingegebenen Keywords verwandt sind.
- Die maximale Batchgröße für Targeting-Kriterien beträgt jetzt 500.
- Die Antwortattribute card_uri und preview_url schließen sich nun gegenseitig aus. Wenn eine Card eine card_uri hat, ist die preview_url null. Wenn eine Card keine card_uri hat, wird nur die preview_url zurückgegeben.
- Alle Cards, die ab 2018-01-29 erstellt wurden, haben eine card_uri.
- Bis Version 4 werden alle bestehenden Cards eine card_uri haben.
- Es ist nicht mehr möglich, Cards mit 5:2-Bildern zu erstellen. Während bestehende, auf 5:2-Bildern basierende Cards weiterhin funktionieren, empfehlen wir Partnern, auf die leistungsstärkeren Seitenverhältnisse 1,91:1 oder 1:1 umzusteigen (wo unterstützt).
- Der PUT accounts/:account_id/targeting_criteria-Endpoint ist nicht mehr verfügbar. Wir haben uns zu dieser Änderung entschlossen, weil das Replace-Verhalten dieses Endpoints bei Werbetreibenden zu Verwirrung geführt hat und nicht mit unseren anderen PUT-Endpunkten konsistent war, die jeweils eine einzelne Ressource aktualisieren. Stattdessen sollten Partner den POST batch/accounts/:account_id/targeting_criteria-Endpoint verwenden, der mehr Flexibilität bietet, einschließlich der Möglichkeit, Targeting in einer einzelnen Anfrage sowohl hinzuzufügen als auch zu entfernen.
- Das Antwortattribut paused wird für Finanzierungsinstrumente nicht mehr zurückgegeben. Verwenden Sie stattdessen das Antwortattribut entity_status, um festzustellen, ob ein Finanzierungsinstrument pausiert ist. Außerdem gilt, dass paused und cancelled demselben Wert entsprechen; daher wird cancelled ebenfalls nicht mehr in der Antwort zurückgegeben.
- Wir haben den Parameter card_id aus dem GET accounts/:account_id/tweet/preview-Endpoint entfernt.
- Da es nicht möglich ist, gelöschte geplante Tweets abzurufen, wird der Parameter with_deleted nicht mehr unterstützt.
- Der Parameter draft_only wurde aus den folgenden Endpoints entfernt, da sich diese Entitäten niemals im Entwurfsstatus befinden können:
v2
-
total_countist jetzt ein optionales Response-Attribut. Es ist nur verfügbar, wennwith_total_countauftruegesetzt ist -
Die
paused- unddraft_only-fields beiline_items- undcampaigns-Request- und -Response-Objekten werden durch einen einzelnenentity_status-Parameter ersetzt -
Der
status-Parameter wurde intextumbenannt bei den POST accounts/:account_id/tweet und GET accounts/:account_id/tweet/preview endpoints -
Die
location_type-Enums des GET targeting_criteria/locations endpoint sind nun im Plural.COUNTRYist jetztCOUNTRIES,REGIONist jetztREGIONSusw. Die einzige Ausnahme ist, dass in v2CITYjetztMETROSist, um korrekt widerzuspiegeln, dass sich der Location-Typ auf Designated Marker Areas (DMAs) oder „Metros“ bezieht. -
display_propertiesauf den PUT accounts/:account_id/promoted_tweets endpoints. Dieser Wert wird auch nicht mehr als Teil der Response zurückgegeben - Infolge des vorherigen Punkts ist es nicht mehr möglich, promoted_tweets-Entities zu aktualisieren (PUT)
-
Der
line_item_id-Parameter am GET accounts/:account_id/promoted_tweets endpoint wurde entfernt - Es wird nicht mehr möglich sein, 5:2 Website Cards auf den v2 endpoints zu erstellen
-
Das
data_type-Response-Attribut wird nicht mehr zurückgegeben
- Cards v2
- Entwurfskampagnen/Erstellung und Aktivierung von Line Items
- Geplante Tweets
- Asynchrone Job-Zusammenfassungen
- Der
card_uri-Request-Parameter sollte bevorzugt werden, anstatt diepreview_urlan den Tweet-Text anzuhängen, wenn eine Card einem Tweet zugeordnet wird - Wenn der
card_uri-Parameter in der Response (während des Card-Erstellungsschritts) nicht zurückgegeben wird, verwenden Sie diepreview_url - Alle neuen Card-Formate sind nativ in der API verfügbar und nutzen den
card_uri-Parameter.
- Video Website Cards:
- Der Parameterwert
entity_statusbei den Endpoints POST accounts/:account_id/line_items und POST accounts/:account_id/campaigns kann aufDRAFTgesetzt werden, um neue Kampagnen- oder Line-Item-Entwürfe zu erstellen. - Erforderliche Parameter für einen neu erstellten Entwurf:
| Draft Campaign | Draft Line Item |
|---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
- Line-Item- oder Kampagnenentwürfe können nur von
DRAFTaufPAUSEDoderACTIVEgesetzt werden. - Um eine gesamte Kampagne (mit mehreren Line Items) zu aktivieren, muss jedes Line Item innerhalb der Kampagne sowie die Kampagne selbst auf
ACTIVEgesetzt werden. - Um den
entity_statuseiner Kampagne oder eines Line Items zu ändern, verwenden Sie den entsprechenden PUT-Endpoint.
- Geplante Tweets werden über die folgenden neuen Endpoints unterstützt
- Geplante Tweets:
- Kampagnenverwaltung:
- Neu geplante Tweets können für beliebige zukünftige Termine eingeplant werden
- Derzeit gibt es keine Möglichkeit, eine Vorschau eines geplanten Tweets anzuzeigen
-
Nur geplante Tweets im Status
SCHEDULEDkönnen bearbeitet/gelöscht werden -
Geplante Tweets werden nicht an den Enterprise-Firehose oder eine andere Daten-API übermittelt, bevor
scheduled_aterreicht ist.
v1
- Unterstützung für Versionierung
CUSTOMZiel wird nicht mehr unterstützt- Batch-Endpunkte sind jetzt allgemein verfügbar
- Änderungen an den Reichweitenschätzungen:
- Um eine genauere Reichweitenschätzung zu ermöglichen, ist das endpoint nun budgetbewusst. Die folgenden Parameter sind jetzt erforderlich:
- [neu]
campaign_daily_budget_amount_local_micro currencybidobjective
- [neu]
- Das Response-Objekt wurde geändert und gibt nun Wertebereiche für Antwortwerte zurück.
infinite_countwurde ininfinite_bid_countumbenannt, um Missverständnisse über seinen Zweck zu vermeiden- Zusätzlich zu
countundinfinite_bid_countwerden nun die folgenden neuen Datenpunkte zurückgegeben:impressionsengagementsestimated_daily_spend_local_micro
- Änderung des Datentyps für maßgeschneiderte Zielgruppen
- Der
data_typefür Tailored Audiences wurde in all unseren Antworten vontailored_audiencesauftailored_audiencegeändert. - Geteilte Tailored Audiences sind jetzt als Beta verfügbar, die ausschließlich per API zugänglich ist. Geteilte Tailored Audiences ermöglichen die Nutzung einer einzelnen Zielgruppe über mehrere Ads-Konten hinweg. Verwenden Sie das endpoint POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (und verwandte), um die Berechtigungen einer Tailored Audience zu verwalten, die Sie über Ads-Konten hinweg freigeben möchten.
- Wesentliche Verbesserungen bei der Erfassung von Leistungsdaten (Analytics) für Werbetreibendenkonten:
- Zur Angleichung an unsere Best Practices erlauben wir ab sofort das Abrufen von data für höchstens 7 Tage über die synchronen Stats-endpoints.
- Um das Abrufen von metrics zu vereinfachen, haben wir den Parameter
metricsdurch den neuen Parametermetric_groupsersetzt. Entwickler müssen lediglich angeben, welche Gruppen von metrics für eine bestimmte Anfrage zurückgegeben werden sollen.- Jede Anforderung nach metrics, die für eine bestimmte Entität nicht relevant sind, wird in der Antwort ausgeschlossen und als
null-Werte dargestellt. Diese metrics werden nicht auf Ihr Analytics-Kostenlimit angerechnet.
- Jede Anforderung nach metrics, die für eine bestimmte Entität nicht relevant sind, wird in der Antwort ausgeschlossen und als
- Die Antwort wurde deutlich vereinfacht und entspricht nun stärker der Art und Weise, wie metrics in unserer UI dargestellt werden.
- Zuvor haben wir für jeden Platzierungsort eine separate Kennzahl bereitgestellt (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). Wir geben nun einen standardisierten Satz von metrics für jede zurück (anstelle von
promoted_tweet_timeline_impressions,promoted_tweet_search_impressions,promoted_tweets_profile_impressions,promoted_tweets_tpn_impressions); diese werden jetzt, wenn sie in einer der folgenden Kategorien angefordert werden, als einzelne Kennzahlimpressionsbereitgestellt (dies gilt für alle metrics): ALL_ON_TWITTERPUBLISHER_NETWORK- Wenn Sie eine Anfrage stellen, erhalten Sie eine einzelne
impressions-Kennzahl, um die Zuordnung der Werte in unserer UI zu vereinfachen. - Sie müssen zwei Abfragen durchführen, um sowohl
ALL_ON_TWITTER- als auchPUBLISHER_NETWORK-data zu erhalten, da diese nicht kombiniert werden können.
- Zuvor haben wir für jeden Platzierungsort eine separate Kennzahl bereitgestellt (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). Wir geben nun einen standardisierten Satz von metrics für jede zurück (anstelle von
- Asynchrone Statistik-endpoints sind jetzt verfügbar – basierend auf dem Feedback unserer Entwickler!
- Ein neues Set von endpoints, um Statistiken asynchron anzufordern – für data, die Sie nicht sofort benötigen, oder für historische Abrufe.
- Stellen Sie einen Statistikauftrag in die Warteschlange, indem Sie ein einziges neues endpoint verwenden. Wir ziehen die von Ihnen angeforderten data, sobald Ressourcen verfügbar sind.
- Sie können ein Jobstatus-endpoint abfragen, um festzustellen, ob die data verfügbar sind.
- Sobald die data verfügbar sind, stellen wir Ihnen eine Abhol-id zur Verfügung, mit der Sie die JSON-Antwort herunterladen können, die die Antwort des synchronen endpoint widerspiegelt.
- Fragen Sie bis zu 90 Tage an data für bis zu 20 Entities in einem einzelnen Auftrag ab.
- Werfen Sie einen Blick in unseren Migrationsleitfaden für analytics v1, der die Zuordnung der v0 metrics zu den v1 metrics enthält
- Verbesserungen der Sandbox * Sie können jetzt in der Sandbox-Umgebung mehrere Test-Ads-Konten erstellen. * Sie können jetzt ausschließlich in der Sandbox-Umgebung mehrere Zahlungsinstrumente für ein Test-Ads-Konto anlegen. Dadurch können Sie alle unsere Arten von Zahlungsinstrumenten testen. Zuvor stand zum Testen nur die Zahlungsquelle
CREDIT_CARDzur Verfügung. * Möchten Sie eine Beta-Funktion testen? Sie können nun in der Sandbox-Umgebung Funktionen für ein Konto ein- oder ausschalten, um Ihre Testanforderungen zu erfüllen.