Analytics

​

Einführung

Analytics-Metriken helfen Partnern und Werbetreibenden, die Leistung der Inhalte zu verstehen, die sie auf X bewerben. Dazu gehören Informationen wie Impressions, Klicks, Videoansichten und Ausgaben. Darüber hinaus können Partner und Werbetreibende detaillierte Metriken für verschiedene Segmente der erreichten Zielgruppen abrufen.

Die Ads API unterstützt zwei Möglichkeiten, detaillierte Kampagnenleistungsmetriken abzurufen: synchron und asynchron. Bei synchronen Analytics-Aufrufen werden die angeforderten Metriken in der Antwort zurückgegeben. Bei den asynchronen Analytics-endpoints stehen die angeforderten Metriken in einer herunterladbaren Ergebnisdatei zur Verfügung, nachdem der zugehörige “Job” die Verarbeitung abgeschlossen hat. Der synchrone endpoint unterstützt kurze Zeitspannen und ist ideal für Echtzeitoptimierungen von Kampagnen. Die asynchronen endpoints unterstützen deutlich längere Zeitspannen und sind daher für das Abrufen wesentlich größerer Datenmengen vorgesehen, ideal zur Erstellung von Berichten oder historischen Backfills.

​

Details

​

Synchron vs. Asynchron

Die Unterschiede zwischen den synchronen und asynchronen Analytics-endpoints sind in der folgenden Tabelle zusammengefasst. Diese Informationen sollen Entwicklerinnen und Entwicklern helfen, das passende Set an endpoints auszuwählen.

Feature	Synchron	Asynchron
Rate Limit	Nutzer-Ebene: 250 Anfragen/15 Minuten	Konto-Ebene: 100 gleichzeitige* Jobs
Zeitraum	7 Tage	90 Tage (nicht segmentiert) 45 Tage (segmentiert)
Segmentierung	Nein	Ja
Antwort enthält	metrics data	Verarbeitungsstatus des Jobs**
Empfohlener Anwendungsfall	Echtzeit-Optimierung Anfragen aus der Benutzeroberfläche	Regelmäßig geplante Synchronisierung Auffüllen historischer data

• Bezieht sich auf die maximale Anzahl von Jobs, die sich zu einem beliebigen Zeitpunkt im Verarbeitungsstatus befinden dürfen.

** Sobald der Job erfolgreich verarbeitet wurde, wird eine URL zurückgegeben, über die die komprimierte (gzip) Ergebnisdatei heruntergeladen werden kann.

Abgesehen davon bieten die endpoints die gleiche Funktionalität.

​

Anwendungsfälle

Es gibt drei zentrale Anwendungsfälle für Analysen.

1. Echtzeitoptimierung: Nutzung von Leistungs-metrics zur Aktualisierung aktiver Kampagnen
2. Synchronisierung: regelmäßig geplante Hintergrundsynchronisierungen
3. Onboarding neuer Konten: Auffüllen historischer data

Das synchrone Analytics-endpoint kann für Echtzeitoptimierung verwendet werden, um Kampagnen basierend auf Änderungen an metrics innerhalb der letzten 5 bis 15 Minuten zu aktualisieren. Für die Analyse-Synchronisierung kann entweder endpoint verwendet werden. Beachten Sie, dass der gewünschte Zeitraum und die Frage, ob Segmentierung erforderlich ist, bestimmen, welches endpoint verwendet werden soll. Das Onboarding neuer Konten sollte nur mit den asynchronen Analytics-endpoints durchgeführt werden. (Das synchrone Analytics-endpoint sollte niemals zum Abrufen großer Mengen an data verwendet werden.)

Die asynchronen Analytics-endpoints können Dashboards und andere UI-Elemente unterstützen, wenn metrics mit einem Backend-Prozess synchronisiert werden. Ihre Implementierung sollte vermeiden, die asynchronen Analytics-endpoints zum Bedienen von Anforderungen der Benutzeroberfläche aufzurufen.

​

Request-Optionen

Analytics-Anfragen sind auf Werbekonten beschränkt und erfordern daher die Konto-id im Ressourcenpfad. Die unten aufgeführten Anfrageoptionen werden als query-Parameter angegeben. Die folgenden Wertetypen sind erforderlich.

• Entities: der Entitätstyp sowie bis zu 20 Entitäts-id, für die Sie Analytics anfordern möchten
• Zeitbereich: die Start- und Endzeiten im Format ISO 8601
  • Hinweis: Muss in vollen Stunden angegeben werden
• Metrikgruppen: eine oder mehrere Gruppen verwandter metrics (siehe Metrics und Segmentation für eine Liste der metrics innerhalb jeder Metrikgruppe)
• Granularität: gibt die Aggregationsebene an, in der die metrics zurückgegeben werden sollen
• Platzierung: gibt an, ob metrics für Anzeigen abgerufen werden, die auf oder außerhalb von X ausgeliefert wurden
  • Hinweis: Pro Anfrage kann nur ein einzelner Platzierungswert angegeben werden

Verwenden Sie die Anfrageparameter start_time und end_time, um einen Zeitbereich anzugeben. Diese Werte müssen wie folgt mit der angegebenen Granularität übereinstimmen.

1. TOTAL: beliebigen Zeitbereich angeben (innerhalb der Grenzen des endpoint)
2. DAY: sowohl Startzeit als auch Endzeit müssen auf Mitternacht in der Zeitzone des Kontos ausgerichtet sein
3. HOUR: beliebigen Zeitbereich angeben (innerhalb der Grenzen des endpoint)

Die Endzeit ist exklusiv. Beispiel: Eine Anfrage mit start_time=2019-01-01T00:00:00Z und end_time=2019-01-02T00:00:00Z gibt die Analytics-metrics für einen einzigen Tag zurück (nicht zwei), da dieser Zeitbereich nur 24 Stunden umfasst.

Segmentierung

Nur über unsere asynchronen Analytics-endpoints verfügbar, ermöglicht die Segmentierung Partnern und Werbetreibenden, metrics nach bestimmten Targeting-Werten aufgeschlüsselt abzurufen. Um segmentierte metrics anzufordern, verwenden Sie den Anfrageparameter segmentation_type. Weitere Details zu Segmentierungsoptionen finden Sie unter Metrics and Segmentation.

​

FAQs

Warum stimmen die Zahlen der Ads API nicht mit denen in der X Ads UI überein?

• Stellen Sie sicher, dass Sie data für alle Platzierungen angefordert haben: ALL_ON_TWITTER sowie PUBLISHER_NETWORK, SPOTLIGHT und TREND.
• Denken Sie daran, dass Endzeiten in der Ads API exklusiv sind; in der Ads UI sind sie hingegen inklusiv.

Warum ändern sich die Zahlen je nach Zeitpunkt der data-Anfrage?

• Sobald Reporting-metrics verfügbar sind, können Sie sie abrufen. Sie stehen nahezu in Echtzeit zur Verfügung. Diese frühen Ergebnisse sind jedoch Schätzungen und werden sich daher voraussichtlich ändern. metrics werden nach 24 Stunden finalisiert, mit Ausnahme der Spend-Daten.
• Spend-metrics sind in der Regel innerhalb von 3 Tagen nach dem Ereignis final. Allerdings verarbeiten wir Abrechnungsdaten bis zu 14 Tage ab dem Datum des Ereignisses (z. B. für Spam-Filterung).

Wie kann ich ermitteln, welche Entity-IDs ich für einen bestimmten Zeitraum anfordern soll?

• Verwenden Sie das Active Entities endpoint

Warum sind alle Werte in der Analytics-Antwort null?

• Es ist wahrscheinlich, dass die Kampagne im angeforderten Zeitraum nicht ausgeliefert wurde.
• Verwenden Sie das Active Entities endpoint, um zu bestimmen, für welche Entities und für welchen Zeitraum Analytics abgerufen werden sollen.

Warum zeigt die API null-Werte, während die UI 0 anzeigt?

• Die UI entscheidet sich, diese Werte als 0 anzuzeigen, die Werte sind jedoch gleichbedeutend.

Wie kann ich metrics anfordern, die einer granularen Platzierung zugeordnet sind, etwa der X-Timeline?

• Wir unterstützen in Analytics die folgenden Platzierungswerte: ALL_ON_TWITTER sowie PUBLISHER_NETWORK, SPOTLIGHT und TREND (d. h. die X Audience Platform).

Ist es möglich, metrics für gelöschte oder pausierte Entities abzurufen?

• Ja. Der Status der Entity wirkt sich nicht auf die Verfügbarkeit von Analytics-metrics aus.

Warum stimmen die segmentierten Werte nicht mit den nicht segmentierten überein?

• Segmentierte data ist aufgrund der Art und Weise, wie diese Informationen abgeleitet werden, nicht darauf ausgelegt, sich zu 100 % auf die nicht segmentierte data aufzusummieren.

Ist es möglich, data segmentiert nach mehreren Dimensionen anzufordern?

• Wir unterstützen keine Multi-Segmentierung.

​

Best Practices

Einige Best Practices beim Erfassen von Analytics-Daten aus der Ads API.

​

Rate Limits und Wiederholungen

• Bei Anfragen, die einer Rate Limit unterliegen (die einen HTTP 429-Statuscode zurückgeben), müssen Sie den Header x-rate-limit-reset prüfen und erst zum bzw. nach dem angegebenen Zeitpunkt erneut versuchen.
• Bei Anfragen, die zu einem HTTP 503 Service Unavailable-Statuscode führen, müssen Sie den Header retry-after prüfen und erst nach dem angegebenen Zeitpunkt erneut versuchen.
• Anwendungen, die die für Wiederholungen angegebenen Zeiten nicht einhalten, können ohne vorherige Ankündigung in ihrem Zugriff auf die Ads API entzogen oder gedrosselt werden.

​

Analytics-Metriken auf einen Blick

• Alle Analytics-Metriken sind fixiert und ändern sich nach 24 Stunden nicht mehr, mit Ausnahme von billed_charge_local_micro.
• Die Metrik billed_charge_local_micro ist bis zu 3 Tage nach der Rückgabe der data ein Schätzwert.
• Nach 24 Stunden kann diese Metrik aufgrund von Gutschriften für Überschreitungen (Anzeigen, die nach dem angegebenen end_time ausgeliefert wurden) sowie für abrechenbare Ereignisse, die als Junk eingestuft werden, sinken. Nach 24 Stunden ändert sich diese Metrik nur noch minimal.
• Weitere Informationen finden Sie unter Analytics.

​

Abrufen von Echtzeit-, nicht segmentierten Daten

• Geben Sie immer sowohl start_time als auch end_time an.
• Rufen Sie keine Daten für Entities ab, die älter als 7 Tage sind.
• Fordern Sie Daten (idealerweise) mit der Granularität HOUR an, da Sie metrics jederzeit aggregieren und zu DAY- bzw. TOTAL-Granularität zusammenführen können.
• Fordern Sie Daten (idealerweise) auf Ebene von line_items und promoted_tweets an, da Sie diese metrics jederzeit aggregieren und zusammenführen können, um Summen über die gesamte Anzeigen-Entitätshierarchie zu erhalten (d. h. auf Kampagnen-, Funding-Instrument- oder Kontoebene).
• Speichern Sie die Werte der Analytics-metrics lokal auf Ihrer Seite.
• Stellen Sie keine wiederholten Abfragen für Daten, die älter als 30 Tage sind. Diese Daten ändern sich nicht und sollten lokal gespeichert werden.
• Alle nicht segmentierten Daten sind Echtzeitdaten und sollten innerhalb von Sekunden nach Eintreten eines Ereignisses verfügbar sein.
• Gruppieren Sie Conversion-metrics und Non-Conversion-metrics in separate Anfragen.

​

Abrufen segmentierter Daten

• Siehe die oben bereitgestellten Richtlinien für „Abrufen von Echtzeit-, nicht segmentierten Daten“. Zusätzliche Hinweise finden Sie unten.
• Bei den meisten segmentierten Datentypen kann es vorkommen, dass die Daten bis zu 1 Stunde lang nicht vollständig sind. Nach INTERESTS segmentierte Daten können sich um bis zu 12 Stunden verzögern.
• Es ist nicht zu erwarten, dass segmentierte Daten zu 100 % mit den nicht segmentierten Daten übereinstimmen, da diese Informationen unterschiedlich abgeleitet werden.

​

Abrufen historischer Daten

• Beim Backfilling von Daten (d. h. beim Hinzufügen eines neuen Werbetreibendenkontos) müssen Sie möglicherweise mehrere Anfragen in kleineren start_time- und end_time-Abschnitten senden.
• Beschränken Sie Ihre Abrufe auf Zeitfenster von 30 Tagen.
• Drosseln Sie diese Anfragen und verteilen Sie sie über die Zeit, um Ihre Rate Limits für diese Abrufe nicht auszuschöpfen.

​

Beispiel

Ein Beispielskript, das einige dieser Best Practices veranschaulicht (fetch_stats), finden Sie in unserem Repository ads-platform-tools GitHub.

​

Metriken nach Ziel

Welche Metriken für eine Entität relevant sind, hängt vom Kampagnenziel ab. Nutzen Sie diesen Leitfaden, um die relevanten Metrikgruppen zu bestimmen, die für jeden Zieltyp abgerufen werden sollten, und wie zusätzliche abgeleitete Metriken berechnet werden können.

​

ENGAGEMENTS

Relevante Metrikgruppen: ENGAGEMENT und BILLING. MEDIA ist ebenfalls relevant, wenn Medien in Creatives verwendet werden.

Abgeleitete Metrik	Berechnung der exponierten Metrik
Engagement-Rate	engagements/impressions
CPE	billed_charge_local_micro/engagements
Media-View-Rate	media_views/impressions

​

WEBSITE_CLICKS und WEBSITE_CONVERSIONS

Relevante Metrikgruppen: ENGAGEMENT, BILLING und WEB_CONVERSION. MEDIA ist ebenfalls relevant, wenn in Creatives Medien verwendet werden.

Abgeleitete Metrik	Sichtbare Metrikberechnung
CPM	billed_charge_local_micro/impressions/1000
Klickrate	clicks/impressions
CPLC	billed_charge_local_micro/clicks
Gesamtanzahl Conversions	conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
Conversion-Rate	Gesamtanzahl Conversions / impressions
CPA	billed_charge_local_micro / Gesamtanzahl Conversions

​

APP_INSTALLS und APP_ENGAGEMENTS

Relevante Metrikgruppen: ENGAGEMENT, BILLING, MOBILE_CONVERSION und LIFE_TIME_VALUE_MOBILE_CONVERSION. MEDIA und VIDEO sind ebenfalls relevant, wenn in Creatives eine Media- oder Video-App-Card verwendet wird.

Abgeleitete Metrik	Offen gelegte Metrikberechnung
CPM	billed_charge_local_micro/impressions/1000
App-Klickrate	app_clicks/impressions
CPAC	billed_charge_local_micro/app_clicks
CPI	billed_charge_local_micro/mobile_conversion_installs

​

FOLLOWERS

Relevante Metrikgruppen: ENGAGEMENT und BILLING. MEDIA ist ebenfalls relevant, wenn in Creatives Medien verwendet werden.

Abgeleitete Metrik	Berechnung der ausgewiesenen Metrik
CPM	billed_charge_local_micro/impressions/1000
Follow-Rate	follows/impressions
CPF	billed_charge_local_micro/follows
Media-View-Rate	media_views/impressions

​

LEAD_GENERATION

Relevante Metrikgruppen: ENGAGEMENT und BILLING. MEDIA ist ebenfalls relevant, wenn in Creatives Medien verwendet werden.

Abgeleitete Metrik	Berechnung der sichtbaren Metrik
CPM	billed_charge_local_micro/impressions/1000
Leads	card_engagements
Lead-Rate	card_engagements/impressions
Kosten pro Lead	billed_charge_local_micro/card_engagements

​

VIDEO_VIEWS

Relevante Metrikgruppen: ENGAGEMENT, BILLING und VIDEO.

Abgeleitete Metrik	Berechnung der offengelegten Metrik
CPM	billed_charge_local_micro/impressions/1000
Videorate	video_total_views/impressions
Kosten pro View	billed_charge_local_micro/video_total_views

​

VIDEO_VIEWS_PREROLL

Relevante Metrikgruppen: ENGAGEMENT, BILLING und VIDEO.

Abgeleitete Metrik	Berechnung der exponierten Metrik
CPM	billed_charge_local_micro/impressions/1000
Videorate	video_total_views/impressions
Kosten pro View	billed_charge_local_micro/video_total_views

​

Metriken und Segmentierung

Dieses Dokument bietet eine Übersicht über die in unseren Analytics für jeden Entitätstyp verfügbaren metrics sowie über die verfügbare Segmentierung für jede metrics.

	Metrikgruppen
Entität	ENGAGEMENT	BILLING	VIDEO	MEDIA	WEB_CONVERSION	MOBILE_CONVERSION	LIFE_TIME_VALUE_MOBILE_CONVERSION
ACCOUNT	✔*
FUNDING_INSTRUMENT	✔*	✔
CAMPAIGN	✔	✔	✔	✔	✔	✔	✔
LINE_ITEM	✔	✔	✔	✔	✔	✔	✔
PROMOTED_TWEET	✔	✔	✔	✔	✔	✔	✔
MEDIA_CREATIVE	✔	✔	✔	✔	✔	✔	✔
ORGANIC_TWEET	✔		✔

*Einige metrics in der ENGAGEMENT-metrics-Familie sind auf der Ebene von ACCOUNT und FUNDING_INSTRUMENT nicht verfügbar. Siehe den Abschnitt ENGAGEMENT für Details.

​

Verfügbare metrics nach metrics-Gruppen

​

ENGAGEMENT

Metric	Beschreibung	Segmentierung verfügbar	Datentyp	Verfügbar für Konto / Funding Instrument
engagements	Gesamtzahl der Engagements	✔	Array von ints	✔
impressions	Gesamtzahl der Impressions	✔	Array von ints	✔
retweets	Gesamtzahl der Retweets	✔	Array von ints	✔
replies	Gesamtzahl der Antworten	✔	Array von ints	✔
likes	Gesamtzahl der likes	✔	Array von ints	✔
follows	Gesamtzahl der Follows	✔	Array von ints	✔
card_engagements	Gesamtzahl der Card-Engagements	✔	Array von ints
clicks	Gesamtzahl der Klicks, einschließlich likes und anderer Engagements	✔	Array von ints
app_clicks	Anzahl der App-Installations- oder App-Öffnungsversuche	✔	Array von ints
url_clicks	Gesamtzahl der Klicks auf den Link oder die Website Card in einer Anzeige, einschließlich Earned	✔	Array von ints
qualified_impressions	Gesamtzahl der qualifizierten Impressions	✔	Array von ints
carousel_swipes	Gesamtzahl der Wischbewegungen auf Carousel-Bildern oder -Videos	✔	Array von ints

​

BILLING

Metrik	Beschreibung	Segmentierung verfügbar	Datentyp
billed_engagements	Gesamtzahl der berechneten Interaktionen	✔	Array aus ints
billed_charge_local_micro	Gesamtausgaben in Micros	✔	Array aus ints

​

VIDEO

Hinweis zu Änderungen an der Definition von Videometrics:

Die Metrik video_total_views innerhalb der VIDEO metrics‑Gruppe erfasst alle Aufrufe, bei denen mindestens 50% des Videos für 2 Sekunden im Sichtbereich waren, gemäß dem MRC‑Standard.

Unsere ursprüngliche Definition eines Videoaufrufs – 100% im Sichtbereich für mindestens 3 Sekunden – bleibt als neue Metrik video_3s100pct_views in der VIDEO metrics‑Gruppe verfügbar. Um weiterhin auf Basis der ursprünglichen Definition zu bieten und abgerechnet zu werden, verwenden Sie die neu verfügbare VIEW_3S_100PCT bid_unit.

Metric	Beschreibung	Segmentierung verfügbar	Datentyp
video_total_views	Gesamtzahl der Videoaufrufe	✔	Array von ints
video_views_25	Gesamtzahl der Aufrufe, bei denen mindestens 25% des Videos angesehen wurden	✔	Array von ints
video_views_50	Gesamtzahl der Aufrufe, bei denen mindestens 50% des Videos angesehen wurden	✔	Array von ints
video_views_75	Gesamtzahl der Aufrufe, bei denen mindestens 75% des Videos angesehen wurden	✔	Array von ints
video_views_100	Gesamtzahl der Aufrufe, bei denen 100% des Videos angesehen wurden	✔	Array von ints
video_cta_clicks	Gesamtzahl der Klicks auf den Call‑to‑Action	✔	Array von ints
video_content_starts	Gesamtzahl der Video‑Wiedergabestarts	✔	Array von ints
video_3s100pct_views	Gesamtzahl der Aufrufe, bei denen mindestens 3 Sekunden abgespielt wurden, während 100% im Sichtbereich waren (Legacy video_total_views)	✔	Array von ints
video_6s_views	Gesamtzahl der Aufrufe, bei denen mindestens 6 Sekunden des Videos angesehen wurden	✔	Array von ints
video_15s_views	Gesamtzahl der Aufrufe, bei denen mindestens 15 Sekunden des Videos oder 95% der Gesamtdauer angesehen wurden	✔	Array von ints

​

MEDIA

Metrik	Beschreibung	Segmentierung verfügbar	Datentyp
media_views	Gesamtzahl der Aufrufe (Autoplay und Klick) von Medien in Videos, Vines, GIFs und Bildern.	✔	Array von ints
media_engagements	Gesamtzahl der Klicks auf Medien in Videos, Vines, GIFs und Bildern.	✔	Array von ints

​

WEB_CONVERSION

Metrik	Beschreibung	Segmentierung verfügbar	Datentyp
conversion_purchases	Anzahl der Conversions des Typs PURCHASE sowie der zugehörige Verkaufsbetrag und die Bestellmenge	nur PLATFORMS	JSON-Objekt
conversion_sign_ups	Anzahl der Conversions des Typs SIGN_UP sowie der zugehörige Verkaufsbetrag und die Bestellmenge	nur PLATFORMS	JSON-Objekt
conversion_site_visits	Anzahl der Conversions des Typs SITE_VISIT sowie der zugehörige Verkaufsbetrag und die Bestellmenge	nur PLATFORMS	JSON-Objekt
conversion_downloads	Anzahl der Conversions des Typs DOWNLOAD sowie der zugehörige Verkaufsbetrag und die Bestellmenge	nur PLATFORMS	JSON-Objekt
conversion_custom	Anzahl der Conversions des Typs CUSTOM sowie der zugehörige Verkaufsbetrag und die Bestellmenge	nur PLATFORMS	JSON-Objekt

​

MOBILE_CONVERSION

Statistiken zu mobilen Conversions sind nur für Werbekonten verfügbar, die für MACT aktiviert sind.

Metrik	Beschreibung	Segmentierung verfügbar	Datentyp
mobile_conversion_spent_credits	Aufschlüsselung mobiler Konversionen vom Typ SPENT_CREDIT nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_installs	Aufschlüsselung mobiler Konversionen vom Typ INSTALL nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_content_views	Aufschlüsselung mobiler Konversionen vom Typ CONTENT_VIEW nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_add_to_wishlists	Aufschlüsselung mobiler Konversionen vom Typ ADD_TO_WISHLIST nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_checkouts_initiated	Aufschlüsselung mobiler Konversionen vom Typ CHECKOUT_INITIATED nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_reservations	Aufschlüsselung mobiler Konversionen vom Typ RESERVATION nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_tutorials_completed	Aufschlüsselung mobiler Konversionen vom Typ TUTORIAL_COMPLETED nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_achievements_unlocked	Aufschlüsselung mobiler Konversionen vom Typ ACHIEVEMENT_UNLOCKED nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_searches	Aufschlüsselung mobiler Konversionen vom Typ SEARCH nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_add_to_carts	Aufschlüsselung mobiler Konversionen vom Typ ADD_TO_CART nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_payment_info_additions	Aufschlüsselung mobiler Konversionen vom Typ PAYMENT_INFO_ADDITION nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_re_engages	Aufschlüsselung mobiler Konversionen vom Typ RE_ENGAGE nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_shares	Aufschlüsselung mobiler Konversionen vom Typ SHARE nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_rates	Aufschlüsselung mobiler Konversionen vom Typ RATE nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_logins	Aufschlüsselung mobiler Konversionen vom Typ LOGIN nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_updates	Aufschlüsselung mobiler Konversionen vom Typ UPDATE nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_levels_achieved	Aufschlüsselung mobiler Konversionen vom Typ LEVEL_ACHIEVED nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_invites	Aufschlüsselung mobiler Konversionen vom Typ INVITE nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_key_page_views	Aufschlüsselung mobiler Konversionen vom Typ KEY_PAGE_VIEW nach post_view und post_engagement	✔	JSON-Objekt
mobile_conversion_downloads	Aufschlüsselung mobiler Konversionen vom Typ DOWNLOAD nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_purchases	Aufschlüsselung mobiler Konversionen vom Typ PURCHASE nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_sign_ups	Aufschlüsselung mobiler Konversionen vom Typ SIGN_UP nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt
mobile_conversion_site_visits	Aufschlüsselung mobiler Konversionen vom Typ SITE_VISIT nach post_view, post_engagement, assisted, order_quantity und sale_amount	✔	JSON-Objekt

​

LIFE_TIME_VALUE_MOBILE_CONVERSION

Statistiken zu mobilen Conversions über die gesamte Lebensdauer sind nur für Werbekonten verfügbar, die für MACT aktiviert sind.

Metric	Beschreibung	Segmentierung verfügbar	Datentyp
mobile_conversion_lifetime_value_purchases	Aufschlüsselung mobiler Conversions des Typs PURCHASE		JSON-Objekt
mobile_conversion_lifetime_value_sign_ups	Aufschlüsselung mobiler Conversions des Typs SIGN_UP		JSON-Objekt
mobile_conversion_lifetime_value_updates	Aufschlüsselung mobiler Conversions des Typs UPDATE		JSON-Objekt
mobile_conversion_lifetime_value_tutorials_completed	Aufschlüsselung mobiler Conversions des Typs TUTORIAL_COMPLETED		JSON-Objekt
mobile_conversion_lifetime_value_reservations	Aufschlüsselung mobiler Conversions des Typs RESERVATION		JSON-Objekt
mobile_conversion_lifetime_value_add_to_carts	Aufschlüsselung mobiler Conversions des Typs ADD_TO_CART		JSON-Objekt
mobile_conversion_lifetime_value_add_to_wishlists	Aufschlüsselung mobiler Conversions des Typs ADD_TO_WISHLIST		JSON-Objekt
mobile_conversion_lifetime_value_checkouts_initiated	Aufschlüsselung mobiler Conversions des Typs CHECKOUT_INITIATED		JSON-Objekt
mobile_conversion_lifetime_value_levels_achieved	Aufschlüsselung mobiler Conversions des Typs LEVEL_ACHIEVED		JSON-Objekt
mobile_conversion_lifetime_value_achievements_unlocked	Aufschlüsselung mobiler Conversions des Typs ACHIEVEMENT_UNLOCKED		JSON-Objekt
mobile_conversion_lifetime_value_shares	Aufschlüsselung mobiler Conversions des Typs SHARE		JSON-Objekt
mobile_conversion_lifetime_value_invites	Aufschlüsselung mobiler Conversions des Typs INVITE		JSON-Objekt
mobile_conversion_lifetime_value_payment_info_additions	Aufschlüsselung mobiler Conversions des Typs PAYMENT_INFO_ADDITION		JSON-Objekt
mobile_conversion_lifetime_value_spent_credits	Aufschlüsselung mobiler Conversions des Typs SPENT_CREDIT		JSON-Objekt
mobile_conversion_lifetime_value_rates	Aufschlüsselung mobiler Conversions des Typs RATE		JSON-Objekt

​

Segmentierung

Die Segmentierungsberichte ermöglichen das Abrufen von metrics, aufgeschlüsselt nach den Werten eines bestimmten Targeting-Typs. Aufgrund der deutlich höheren Komplexität ist die Segmentierung nur über asynchrone Analytics-Abfragen verfügbar.

Die Segmentierung wird nicht für MEDIA_CREATIVE- oder ORGANIC_TWEET-Entitäten unterstützt.

Einige Segmentierungsarten erfordern zusätzliche Parameter. Diese sind unten dokumentiert.

Bei der Segmentierung nach CITIES oder POSTAL_CODES gibt die API nur zielgerichtete Standorte zurück. Segmentierungen nach Regionen und Metropolgebieten geben sowohl zielgerichtete als auch nicht zielgerichtete Standorte zurück.

Segmentierungstyp	country-Parameter erforderlich	platform-Parameter erforderlich
AGE
APP_STORE_CATEGORY
AUDIENCES
CITIES	✔
CONVERSATIONS
CONVERSION_TAGS
DEVICES		✔
EVENTS
GENDER
INTERESTS
KEYWORDS
LANGUAGES
LOCATIONS
METROS	✔
PLATFORMS
PLATFORM_VERSIONS		✔
POSTAL_CODES	✔
REGIONS	✔
SLIDES
SIMILAR_TO_FOLLOWERS_OF_USER
TV_SHOWS

​

Abgeleitete Metriken

Kampagnen-metrics hängen von ihrem Kampagnenziel ab. Verwenden Sie diesen Leitfaden, um zu bestimmen, wie abgeleitete metrics basierend auf den jeweiligen Zielen berechnet werden.

Jede metric ohne geschweifte Klammern wird von den Ads API analytics endpoints zurückgegeben. Jeder Name, der von {geschweiften Klammern} umgeben ist, kennzeichnet eine abgeleitete metric für diese Kategorie.

​

INTERAKTIONEN

Abgeleitete Kennzahl	Offen gelegte Metrikberechnung
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Total Engagements}	promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements oder promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows
{Engagement-Rate}	{Total Engagements} / {Impressions}
billed_charge_local_micro / {Total Engagements}
{Media Views}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media-View-Rate}	{Media Views} / {Impressions}

​

WEBSITE_CLICKS

Abgeleitete Metrik	Berechnung der ausgewiesenen Metrik
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Link Clicks}	promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks
{Click-Rate}	{Link Clicks} / {Impressions}
billed_charge_local_micro / {Link Clicks}
conversion_site_visits
{Conversion-Rate}	conversion_site_visits / {Impressions}
billed_charge_local_micro / conversion_site_visits

​

APP_INSTALLS und APP_ENGAGEMENTS

Abgeleitete Kennzahl	Berechnung der bereitgestellten Kennzahl
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions
billed_charge_local_micro / {Impressions} / 1000
{App Clicks}	promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks
{App Click Rate}	{App Clicks} / {Impressions}
billed_charge_local_micro / {App Clicks}
billed_charge_local_micro / mobile_conversion_installs

​

FOLLOWERS

Abgeleitete Metrik	Berechnung der exponierten Metrik
promoted_account_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_account_follows
{Follow Rate}	promoted_account_follow_rate
billed_charge_local_micro / promoted_account_follows
{Media Views}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}	{Media Views} / {Impressions}

​

LEAD_GENERATION

Abgeleitete Kennzahl	Berechnung der veröffentlichten Kennzahl
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_tweet_search_card_engagements + promoted_tweet_timeline_card_engagements + promoted_tweet_profile_card_engagements
{Lead-Rate}	{Leads} / {Impressions}
{Kosten pro Lead}	billed_charge_local_micro / {Leads}

​

VIDEO_VIEWS

Abgeleitete Metrik	Offenlegte Metrikberechnung
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Video Views}	promoted_video_total_views
{Video Rate}	promoted_video_total_views / {Impressions}
{Cost Per View}	billed_charge_local_micro / promoted_video_total_views

​

QUALIFIED_IMPRESSIONS

Abgeleitete Kennzahl	Berechnung der ausgewiesenen Kennzahl
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Qualified Impressions}	promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions
{Qualified Impression Rate}	{Qualified Impressions} / {Impressions}
{Cost Per 1000 Qualified Impressions }	billed_charge_local_micro / {Qualified Impressions} / 1000

​

CUSTOM

Für placement_type von PROMOTED_ACCOUNT siehe das obenstehende Ziel FOLLOWERS. Für alle anderen Platzierungen mit diesem Ziel siehe ENGAGEMENTS für die entsprechenden abgeleiteten metrics.

​

Leitfäden

​

Aktive Entitäten

​

Einführung

Der Active-Entities-endpoint ist dafür vorgesehen, zusammen mit unseren synchronen und asynchronen Analytics-endpoints verwendet zu werden, da er angibt, für welche Kampagnen Analytics abgefragt werden sollten. Dazu gibt er Details zu Anzeigen-Entities zurück und wann sich deren metrics geändert haben. Die Verwendung dieses endpoints vereinfacht Ihren Code und die Logik zum Abrufen von Analytics erheblich.

Dieser Leitfaden beschreibt den endpoint und seine Datenquelle. Außerdem enthält er Nutzungsrichtlinien und eine Reihe von Beispielanfragen, die zeigen, wie Active Entities in Verbindung mit unseren Analytics-endpoints verwendet werden. Der Zusammenfassungsabschnitt bietet eine übergeordnete Beschreibung des empfohlenen Vorgehens.

​

Daten

Immer wenn sich eine Metrik einer Anzeigenentität ändert, protokollieren wir Informationen zu dieser Änderung. Diese Änderungsereignisse werden in stündlichen Buckets gespeichert und enthalten Details zur Entität sowie den Zeitpunkt, für den die Änderung gilt. Letzteres ist notwendig, weil Änderungsereignisse nicht immer mit dem Zeitpunkt übereinstimmen, zu dem sie erfasst wurden. Abrechnungsanpassungen sind ein häufiger Grund dafür, aber es gibt auch andere.

​

Endpoint

​

Anfrage

Active-Entities-Anfragen sind Ads-Konten zugeordnet und haben drei erforderliche Abfrageparameter: entity, start_time und end_time.

twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z"

Die folgenden entity-Werte werden unterstützt: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT und PROMOTED_TWEET. Dies entspricht den Entitätstypen, die unsere Analytics-endpoints unterstützen.

Die Werte für start_time und end_time müssen im Format ISO 8601 angegeben sein und bestimmen, welche stündlichen Buckets abgefragt werden. Diese müssen ganze Stunden sein.

Dieses endpoint unterstützt außerdem drei optionale Parameter, mit denen Ergebnisse gefiltert werden können: funding_instrument_ids, campaign_ids und line_item_ids. Diese funktionieren auf allen Ebenen der Ads-Hierarchie und mit jedem angegebenen entity-Typ.

​

Antwort

Die Active-Entities-Antwort für die oben stehende Anfrage ist unten dargestellt.

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-03-05T00:00:00Z",
          "end_time": "2019-03-06T00:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2r0wxw",
          "activity_start_time": "2019-03-04T20:55:20Z",
          "activity_end_time": "2019-03-05T03:43:56Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2r30fn",
          "activity_start_time": "2019-03-05T08:11:08Z",
          "activity_end_time": "2019-03-05T14:40:59Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }

Das Array data enthält ein Objekt für jede Entität, die in einer nachfolgenden Analytics-Anfrage berücksichtigt werden soll. Fordern Sie keine Analytics für IDs außerhalb dieser Menge an.

Jedes Objekt enthält vier fields: entity_id, activity_start_time, activity_end_time und placements. Die Start- und Endzeiten der Aktivität geben den Zeitraum an, für den die Änderungsereignisse der zugehörigen Entität gelten, und bestimmen damit die Daten, die in nachfolgenden Analytics-Anfragen angegeben werden sollten. Das Array placements kann die folgenden Werte enthalten: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT und TREND. Es gibt an, welche Platzierungen für die angegebene Entitäts-id angefordert werden sollten.

​

Verwendung

Das Active-Entities-endpoint sollte vorgeben, wie Analytics-Anfragen gestellt werden. Die folgenden Nutzungshinweise unterstützen die Analytics-Synchronisierung und ermöglichen Partnern, ihre Datenspeicher mit Twitter synchron zu halten. Anders ausgedrückt: Sie beschreiben, wie regelmäßig geplante Hintergrundsynchronisierungen durchgeführt werden.

Es gibt zwei Entscheidungen, die ein Entwickler treffen muss.

1. Wie oft Informationen zu aktiven Entities abgefragt werden und damit, wie oft Analytics abgerufen werden.
2. Wie die Start- und Endzeiten der Aktivität verwendet werden, um die Werte für start_time und end_time der Analytics-Anfrage festzulegen.

Diese Punkte werden nach der Zusammenfassung in den beiden folgenden Unterabschnitten ausführlicher behandelt.

​

Zusammenfassung

Verwenden Sie das Active-Entities-endpoint wie folgt, um festzulegen, wie Analytics-Anfragen gestellt werden. Befolgen Sie diese Schritte, nachdem Sie entschieden haben, wie oft Sie Informationen zu aktiven Entitäten anfordern und damit, wie häufig Sie Analytics abrufen.

1. Senden Sie die Active-Entities-Anfrage.
2. Teilen Sie die Antwort nach Placement auf: eine Gruppe für ALL_ON_TWITTER, eine für PUBLISHER_NETWORK, eine für SPOTLIGHT und eine für TREND.
3. Führen Sie für jede Placement-Gruppe Folgendes aus.
   1. Extrahieren Sie die Entitäts-IDs.
   2. Bestimmen Sie die Analytics-Werte für start_time und end_time.
      • Ermitteln Sie die minimale activity_start_time. Runden Sie diesen Wert ab.
      • Ermitteln Sie die maximale activity_end_time. Runden Sie diesen Wert auf.
   3. Senden Sie die Analytics-Anfrage(n).
      • Gruppieren Sie die Entitäts-IDs in Batches zu 20.
      • Verwenden Sie die start_time- und end_time-Werte aus Schritt 3b.
      • Geben Sie den passenden placement-Wert an.
   4. Schreiben Sie in Ihren Datenspeicher.

Siehe active_entities.py als Beispiel, das das Python-SDK verwendet.

​

Häufigkeit

Die Antwort auf die erste Frage bestimmt den Zeitraum, der in Active-Entities-Anfragen verwendet werden sollte. Wenn beispielsweise stündlich Informationen zu aktiven Entitäten angefordert werden, sollte der Zeitraum eine Stunde betragen. Wenn Informationen zu aktiven Entitäten einmal täglich angefordert werden, sollte der Zeitraum einen Tag betragen. Mit anderen Worten: Zeiträume sollten so gewählt werden, dass die start_time der aktuellen Anfrage der end_time der vorherigen Anfrage entspricht.

Hinweis: Ein Zeitfenster sollte nur einmal angefordert werden. Das mehrfache Anfordern eines Zeitfensters führt zu unnötigen Analytics-Anfragen. (Ausnahme unten.)

Für Partner, die innerhalb der aktuellen Stunde mehrmals pro Stunde Analytics anfordern möchten, gilt dasselbe Muster — die Häufigkeit bestimmt den Zeitraum. Die Tabelle unten zeigt beispielhafte Start- und Endzeitstempel für Active Entities in diesem Szenario.

Anfragezeit	start_time-Zeitstempel	end_time-Zeitstempel
00:15:00	00:00:00	00:15:00
00:30:00	00:15:00	00:30:00
00:45:00	00:30:00	00:45:00
01:00:00	00:45:00	01:00:00

Aufgrund der Art, wie Änderungsereignisse gespeichert werden, richten sich alle vier oben genannten Active-Entities-Anfragen an denselben stündlichen Bucket, was für diesen Anwendungsfall erforderlich ist. Nach Ablauf der aktuellen Stunde sollte dieser stündliche Bucket jedoch nicht mehr abgefragt werden.

​

Aktivitätszeiten

Wir empfehlen den folgenden Ansatz für den Umgang mit Start- und Endzeiten von Aktivitäten: Ermitteln Sie über alle Objekte in der Active-Entities-Antwort hinweg das minimale activity_start_time und das maximale activity_end_time. Passen Sie diese Werte an, indem Sie die minimale Startzeit nach unten und die maximale Endzeit nach oben runden. Setzen Sie konkret die Zeitstempel in beiden Fällen auf null und addieren Sie einen Tag zur Endzeit, wie in der folgenden Tabelle dargestellt. Diese Start- und Endzeiten sollten in nachfolgenden Analytics-Anfragen angegeben werden.

Min./Max. Aktivitätszeiten	Abgeleitete Zeiten
2019-03-04T20:55:20Z 2019-03-05T14:40:59Z	2019-03-04T00:00:00Z 2019-03-06T00:00:00Z

Hinweis: Es ist wichtig, die Zeitstempel mit auf null gesetzten Stunden, Minuten und Sekunden anzugeben. Andernfalls – wenn nur das Datum übergeben wird – gehen wir davon aus, dass Sie Analytics beginnend und endend um Mitternacht in der Zeitzone des Ads-Kontos anfordern, was möglicherweise nicht wünschenswert ist. Wenn beispielsweise die minimale Aktivitätsstartzeit 2019-02-28T01:30:07Z ist und der Zeitstempel für ein Ads-Konto mit einem Offset von -08:00:00 weggelassen wird, verpasst die Analytics-Anfrage Änderungen, die zwischen 01:30 und 08:00 stattgefunden haben.

Alternativ können Sie Analytics auch nur für das zurückgegebene Aktivitätszeitfenster anfordern, ohne auf ganze Tage zu erweitern. Bei diesem Ansatz lägen die abgeleiteten Start- und Endzeiten bei 2019-03-04T20:00:00Z bzw. 2019-03-05T15:00:00Z. (Beachten Sie, dass solche Zeiträume nicht akzeptiert werden, wenn Sie DAY-Granularität in der Analytics-Anfrage angeben.)

​

Beispiel

Dieser Abschnitt zeigt, wie Active Entities zusammen mit dem synchronen Analytics-endpoint verwendet werden. (Die Antworten wurden zur besseren Lesbarkeit leicht angepasst.) In diesem Beispiel wird der Active Entities-endpoint zu jeder vollen Stunde aufgerufen, wobei jede Anfrage die vorherige Stunde betrachtet. Die Antwort bestimmt, wie der synchrone Analytics-endpoint verwendet wird.

Die erste Active Entities-Anfrage erfolgt um 03:00:00. Die Antwort gibt an, dass sich die metrics des Line Items dvcz7 geändert haben und dass diese Änderungsereignisse für das Zeitfenster zwischen 02:02:55 und 02:28:12 gelten.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:02:55Z",
          "activity_end_time": "2019-02-11T02:58:12Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }

Auf Grundlage dieser Start- und Endzeiten der Aktivität und mithilfe des oben beschriebenen Ansatzes werden die Analytics-Werte start_time und end_time auf 2019-02-11T00:00:00Z bzw. 2019-02-12T00:00:00Z gesetzt. Wir sehen, dass das dritte Element in jedem der unten aufgeführten metrics-Arrays ungleich Null ist, wie anhand der Informationen zu aktiven Entitäten zu erwarten war.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }

Die nächste Active-Entities-Anfrage erfolgt um 04:00:00 und berücksichtigt nur die vorherige Stunde. Wie oben erwähnt, sollte ein Zeitfenster nur einmal angefordert werden. Aus der Antwort geht hervor, dass Änderungsereignisse für dieses Line Item sowohl um 02:00:00 als auch um 03:00:00 gelten. In der anschließenden Analytics-Anfrage erwarten wir, Änderungen für beide Stunden zu sehen.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:07:17Z",
          "activity_end_time": "2019-02-11T03:49:22Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }

Zusätzlich zu nicht-null metrics für 03:00:00 sehen wir, dass Impressions, Ausgaben und MRC-Videoaufrufe gegenüber ihren vorherigen Werten aktualisiert wurden. Die Impressions liegen beispielsweise nun bei 2.995 für die Stunde 02:00:00, zuvor waren es 2.792. Das zeigt, wie während der Stunde 03:00:00 erfasste Änderungsereignisse auf die Stunde 02:00:00 angewendet werden.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }

Die Active-Entities-Anfrage um 05:00:00, wobei erneut nur die vorherige Stunde betrachtet wird, zeigt, dass Änderungsereignisse ausschließlich die Stunde 03:00:00 betreffen. Die Änderungen an den Analytics-metrics in der nachfolgenden Anfrage spiegeln dies wider.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T03:42:39Z",
          "activity_end_time": "2019-02-11T03:48:48Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }

Die Analytics-Antwort zeigt, dass sich nur die metrics für die Stunde 03:00:00 geändert haben; die Werte für die Stunde 02:00:00 sind dieselben wie bei der vorherigen Analytics-Abfrage.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }

Schließlich sehen wir um 06:00:00, dass es keine zusätzlichen Änderungsereignisse gibt. Hinweis: Das bedeutet jedoch nicht, dass sich die metrics für dieses Line Item in Zukunft nicht ändern können.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"`

    {
      "request": {},
      "data": []
    }

​

Leitfaden zur Asynchronität

​

API-Referenz

​

Asynchrone Analytik

​

Einführung

Die asynchronen Analytics-endpoints ermöglichen Partnern und Werbetreibenden, durch das Einreichen von Erstellungsanfragen metrics anzufordern, die der Server asynchron verarbeitet. (Wir bezeichnen diese als asynchrone Analytics-„Jobs“.) Bei diesem Ansatz muss die Verbindung des Clients nicht offen bleiben, bis die Anfrage erfüllt wurde.

Diese endpoints ermöglichen – wie ihre synchronen Gegenstücke – Partnern und Werbetreibenden, detaillierte Statistiken zur Kampagnenleistung anzufordern. Sie unterstützen die Anforderung von data für Konten, Zahlungsmittel, Kampagnen, Line Items, Promoted Tweets und Media Creatives. Der Unterschied zum synchronen endpoint besteht darin, dass die asynchronen Analytics-endpoints längere Datumsbereiche von bis zu 90 Tagen sowie Segmentierung unterstützen. Weitere Details zu den Unterschieden zwischen beiden finden Sie auf unserer Seite Analytics Overview.

Im Gegensatz zu unseren synchronen endpoints basiert das Rate Limit auf der Anzahl gleichzeitiger Jobs für ein bestimmtes Konto. Mit anderen Worten: Es basiert auf der Anzahl der Jobs, die sich zu einem gegebenen Zeitpunkt im Verarbeitungsstatus befinden können. Wir zählen dies auf Ebene des Ads-Kontos.

​

Verwendung

Das Abrufen von Kampagnen-Metriken über die asynchronen Analytics-Endpoints ist ein mehrstufiger Prozess. Er umfasst das Erstellen eines Jobs, die Prüfung, ob die Verarbeitung des Jobs abgeschlossen ist, und schließlich das Herunterladen der Daten. Die Datendatei muss dekomprimiert werden. Die vier konkreten Schritte sind unten beschrieben.

1. Erstellen Sie den Job mithilfe des Endpoints POST stats/jobs/accounts/:account_id.
2. Senden Sie in regelmäßigen Abständen Anfragen an den Endpoint GET stats/jobs/accounts/:account_id, um festzustellen, ob die Verarbeitung des Jobs abgeschlossen ist.
3. Sobald die Verarbeitung des Jobs abgeschlossen ist, laden Sie die Datendatei herunter.
4. Entpacken Sie die Datendatei.

Das im data zurückgegebene Response-Objekt hat dasselbe JSON-Schema wie die Antwort des synchronen Analytics-Endpoints.

Segmentierte Kampagnen-Metriken sind nur über die asynchronen Analytics-Endpoints verfügbar. Kampagnen-Metriken können nach Standort, Geschlecht, Interesse, Keyword und mehr aufgeschlüsselt werden. Eine vollständige Liste der Optionen finden Sie auf der Seite Metrics and Segmentation. Um segmentierte Metriken anzufordern, verwenden Sie den Request-Parameter segmentation_type, wenn Sie den Job erstellen.

​

Beispiel

Dieser Abschnitt zeigt, wie die asynchronen Analytics-endpoints verwendet werden.

Beginnen Sie damit, einen Job mithilfe des endpoint POST stats/jobs/accounts/:account_id zu erstellen. Im folgenden Beispiel werden Engagement-metrics—wie impressions, likes, Klicks usw.—für ein bestimmtes Line Item über den Zeitraum einer Woche angefordert. (Beachten Sie, dass der angeforderte Zeitraum bis zum 20. März reicht, diesen jedoch nicht einschließt, da der Zeitstempel auf Mitternacht gesetzt ist.)

$ twurl -X POST -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2019-03-12T00:00:00Z&end_time=2019-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"

    {
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      },
      "data": {
        "start_time": "2019-03-12T00:00:00Z",
        "segmentation_type": null,
        "url": null,
        "id_str": "1120829647711653888",
        "entity_ids": [
          "el32n"
        ],
        "end_time": "2019-03-20T00:00:00Z",
        "country": null,
        "placement": "ALL_ON_TWITTER",
        "id": 1120829647711653888,
        "expires_at": null,
        "account_id": "18ce54d4x5t",
        "status": "PROCESSING",
        "granularity": "TOTAL",
        "entity": "LINE_ITEM",
        "created_at": "2019-04-23T23:19:46Z",
        "platform": null,
        "updated_at": "2019-04-23T23:19:46Z",
        "metric_groups": [
          "ENGAGEMENT"
        ]
      }
    }

Diese Antwort enthält keine line-item-metrics. Sie liefert lediglich Informationen über den soeben erstellten Job. Die Job-ID wird benötigt, um den Status des Jobs zu prüfen. Dies ist in den Antwortattributen id und id_str ersichtlich.

Als Nächstes sollten Sie prüfen, ob der von Ihnen erstellte Job mit der id_str aus der vorherigen Antwort die Verarbeitung abgeschlossen hat, was in der Antwort durch "status": "SUCCESS" angezeigt wird. Das bedeutet, dass die data zum Download bereitstehen. Das Feld url enthält den Downloadlink.

$ twurl -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"

    {
      "request": {
        "params": {
          "job_ids": [
            1120829647711653888
          ]
        }
      },
      "next_cursor": "1120828505715920896",
      "data": [
        {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "url": "https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz",
          "id_str": "1120829647711653888",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "id": 1120829647711653900,
          "expires_at": "2019-04-25T23:19:48Z",
          "account_id": "18ce54d4x5t",
          "status": "SUCCESS",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "created_at": "2019-04-23T23:19:46Z",
          "platform": null,
          "updated_at": "2019-04-23T23:19:48Z",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      ]
    }

Während wir im obigen Beispiel eine einzelne Job-ID übergeben, sollten Sie in der Praxis den Parameter job_ids verwenden, um den Status mehrerer Jobs gleichzeitig zu überprüfen, indem Sie bis zu 200 Job-IDs angeben.

Laden Sie anschließend die Datendatei mit dem aufgeführten url-Wert herunter.

    $ wget https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    --2019-04-23 17:52:12--  https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    Auflösen von ton.twimg.com (ton.twimg.com)... 72.21.91.70
    Verbinden mit ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... verbunden.
    HTTP-Anfrage gesendet, warte auf Antwort... 200 OK
    Länge: 381 [application/gzip]
    Speichern unter: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

    zBkuuPeEVx-5OygDVcZpqNtwt51Z5 100%[=================================================>]     381  --.-KB/s    in 0s

    2019-04-23 17:52:12 (5.27 MB/s) - 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' gespeichert [381/381]

Zum Schluss die Datei entpacken.

`$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz`

Der Inhalt der Datei wird unten angezeigt.

`$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json`

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "el32n",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  3482
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": [
                  102
                ],
                "unfollows": null,
                "likes": [
                  15
                ],
                "engagements": [
                  171
                ],
                "clicks": [
                  30
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​

Reichweite und durchschnittliche Frequenz

In Postman öffnen

​

GET stats/accounts/:account_id/reach/campaigns

Abrufen von Reichweite und durchschnittlicher Frequenz für die angegebenen Kampagnen.

​

Ressourcen-URL

https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns

​

Parameter

Name	Beschreibung
account_id erforderlich	Der Bezeichner für das verwendete Konto. Er erscheint im Ressourcenpfad und ist in der Regel ein erforderlicher Parameter für alle Advertiser-API-Anfragen mit Ausnahme von GET accounts. Das angegebene Konto muss dem authentifizierten Nutzer zugeordnet sein. Typ: string Beispiel: 18ce54d4x5t
campaign_ids erforderlich	Beschränken Sie die Antwort auf die gewünschten Kampagnen, indem Sie eine durch Kommata getrennte Liste von Bezeichnern angeben. Es können bis zu 20 IDs angegeben werden. Hinweis: Es können bis zu 20 Kampagnen-IDs angegeben werden. Typ: string Beispiel: 8fgzf
end_time erforderlich	Beschränkt die abgerufenen data auf die angegebene Endzeit, angegeben im Format ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-26T07:00:00Z
start_time erforderlich	Beschränkt die abgerufenen data auf die angegebene Startzeit, angegeben im Format ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-19T07:00:00Z

​

Beispielanfrage

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26

​

Beispielantwort

    {
      "request": {
        "params": {
          "campaign_ids": [
            "8fgzf"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "8fgzf",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​

GET stats/accounts/:account_id/reach/funding_instruments

Rufen Sie Reichweiten- und Durchschnittsfrequenz-Analysen für angegebene Funding-Instrumente ab.

​

Ressourcen-URL

https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments

​

Parameter

Name	Beschreibung
account_id erforderlich	Der Bezeichner für das verwendete Konto. Er erscheint im Ressourcenpfad und ist in der Regel ein erforderlicher Parameter für alle Advertiser-API-Anfragen mit Ausnahme von GET accounts. Das angegebene Konto muss dem authentifizierten Benutzer zugeordnet sein. Typ: string Beispiel: 18ce54d4x5t
funding_instrument_ids erforderlich	Beschränken Sie die Antwort auf die gewünschten Zahlungsinstrumente, indem Sie eine kommagetrennte Liste von Bezeichnern angeben. Es können bis zu 20 IDs angegeben werden. Hinweis: Es können bis zu 20 IDs für Zahlungsinstrumente angegeben werden. Typ: string Beispiel: lygyi
end_time erforderlich	Beschränkt die abgerufenen data auf die angegebene Endzeit, ausgedrückt in ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-26T07:00:00Z
start_time erforderlich	Beschränkt die abgerufenen data auf die angegebene Startzeit, ausgedrückt in ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-19T07:00:00Z

​

Beispielanfrage

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2017-05-19&end_time=2017-05-26

​

Beispielantwort

    {
      "request": {
        "params": {
          "funding_instrument_ids": [
            "lygyi"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "lygyi",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​

Synchrone Analysen

In Postman öffnen

​

GET stats/accounts/:account_id

Rufen Sie synchrone Analytics für das aktuelle Konto ab. Ein maximaler Zeitraum (end_time - start_time) von 7 Tagen ist zulässig.

​

Ressourcen-URL

https://ads-api.x.com/12/stats/accounts/:account_id

​

Parameter

Name	Beschreibung
account_id erforderlich	Der Bezeichner für das genutzte Konto. Er erscheint im Pfad der Ressource und ist in der Regel ein erforderlicher Parameter für alle Advertiser-API‑Anfragen mit Ausnahme von GET accounts. Das angegebene Konto muss dem authentifizierten Nutzer zugeordnet sein. Typ: string Beispiel: 18ce54d4x5t
end_time erforderlich	Beschränkt die abgerufenen data auf die angegebene Endzeit, ausgedrückt im Format ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-26T07:00:00Z
entity erforderlich	Der Entitätstyp, für den data abgerufen werden sollen. Typ: enum Mögliche Werte: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids erforderlich	Die spezifischen Entitäten, für die data abgerufen werden sollen. Geben Sie eine kommagetrennte Liste von Entitäts-IDs an. Hinweis: Es können bis zu 20 Entitäts-IDs angegeben werden. Typ: string Beispiel: 8u94t
granularity erforderlich	Gibt an, wie fein granular die abgerufenen data sein sollen. Typ: enum Mögliche Werte: DAY, HOUR, TOTAL
metric_groups erforderlich	Die spezifischen metrics, die zurückgegeben werden sollen. Geben Sie eine kommagetrennte Liste von Metrikgruppen an. Weitere Informationen finden Sie unter Metrics and Segmentation. Hinweis: MOBILE_CONVERSION data sollten separat angefordert werden. Typ: enum Mögliche Werte: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement erforderlich	Beschränkt die abgerufenen data auf eine bestimmte Platzierung. Hinweis: Pro Anfrage wird nur ein einzelner Wert akzeptiert. Für Entitäten mit Platzierungen sowohl auf X als auch auf der X Audience Platform sind separate Anfragen erforderlich, jeweils eine pro Platzierungswert. Typ: enum Mögliche Werte: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time erforderlich	Beschränkt die abgerufenen data auf die angegebene Startzeit, ausgedrückt im Format ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-19T07:00:00Z

​

Beispielanfrage

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT

​

Beispielantwort

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "8u94t",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  1233
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": null,
                "likes": [
                  1
                ],
                "engagements": [
                  58
                ],
                "clicks": [
                  58
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2017-05-19T07:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "8u94t"
          ],
          "end_time": "2017-05-26T07:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​

Aktive Entitäten

In Postman öffnen

​

GET stats/accounts/:account_id/active_entities

Rufen Sie Details dazu ab, bei welchen Entitäten sich die Analytics-metrics in einem bestimmten Zeitraum geändert haben.

Dieser endpoint sollte in Verbindung mit unseren Analytics-endpoints verwendet werden. Die Ergebnisse dieses endpoints geben an, für welche Ads-Entitäten Analytics angefordert werden sollen. Hinweise zur Verwendung finden Sie in unserem Active Entities Guide.

Änderungsereignisse sind in stündlichen Buckets verfügbar.

• Die Werte start_time und end_time geben an, welche stündlichen Buckets abgefragt werden.
• Das zurückgegebene data-Array enthält ein Objekt für jede Entität, die in nachfolgenden Analytics-Anfragen berücksichtigt werden sollte.
• WICHTIG: Die Zeiträume, die in nachfolgenden Analytics-Anfragen angegeben werden sollten, sind anhand der Werte activity_start_time und activity_end_time zu bestimmen.
  • Diese Werte stehen für die Zeitspannen, auf die die gespeicherten Änderungsereignisse angewendet werden. Dies wird pro Entität zurückgegeben.

Hinweis: Eine maximale Zeitspanne (end_time - start_time) von 90 Tagen ist zulässig.

​

Ressourcen-URL

https://ads-api.x.com/12/stats/accounts/:account_id/active_entities

​

Parameter

Name	Beschreibung
account_id erforderlich	Der Bezeichner für das verwendete Konto. Er erscheint im Pfad der Ressource und ist in der Regel ein erforderlicher Parameter für alle Advertiser-API-Anfragen mit Ausnahme von GET accounts. Das angegebene Konto muss dem authentifizierten Nutzer zugeordnet sein. Typ: string Beispiel: 18ce54d4x5t
end_time erforderlich	Begrenzt die abgerufenen data auf die angegebene Endzeit, ausgedrückt in ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-26T07:00:00Z
entity erforderlich	Der Entitätstyp, für den data abgerufen werden sollen. Typ: enum Mögliche Werte: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time erforderlich	Begrenzt die abgerufenen data auf die angegebene Startzeit, ausgedrückt in ISO 8601. Hinweis: Muss in vollen Stunden angegeben werden (0 Minuten und 0 Sekunden). Typ: string Beispiel: 2017-05-19T07:00:00Z
campaign_ids optional	Beschränken Sie die Antwort auf Entitäten, die mit den gewünschten Kampagnen verknüpft sind, indem Sie eine kommagetrennte Liste von Bezeichnern angeben. Es können bis zu 200 IDs übermittelt werden. Hinweis: Exklusiv zu funding_instrument_ids und line_item_ids. Typ: string Beispiel: 8wku2
funding_instrument_ids optional	Beschränken Sie die Antwort auf Entitäten, die mit den gewünschten Zahlungsinstrumenten verknüpft sind, indem Sie eine kommagetrennte Liste von Bezeichnern angeben. Es können bis zu 200 IDs übermittelt werden. Hinweis: Exklusiv zu campaign_ids und line_item_ids. Typ: string Beispiel: lygyi
line_item_ids optional	Beschränken Sie die Antwort auf Entitäten, die mit den gewünschten Line Items verknüpft sind, indem Sie eine kommagetrennte Liste von Bezeichnern angeben. Es können bis zu 200 IDs übermittelt werden. Hinweis: Exklusiv zu campaign_ids und line_item_ids. Typ: string Beispiel: 8v7jo

​

Beispielanfrage

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01

​

Beispielantwort

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-02-28T08:00:00Z",
          "end_time": "2019-03-01T08:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2mvb28",
          "activity_start_time": "2019-02-28T01:30:07Z",
          "activity_end_time": "2019-03-01T07:42:55Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2mvb29",
          "activity_start_time": "2019-02-27T11:30:07Z",
          "activity_end_time": "2019-03-01T07:42:50Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2mvfan",
          "activity_start_time": "2019-02-27T09:00:05Z",
          "activity_end_time": "2019-03-01T06:06:36Z",
          "placements": [
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2n17dx",
          "activity_start_time": "2019-02-28T02:02:26Z",
          "activity_end_time": "2019-03-01T07:52:44Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }