Outlier-Videosuche
Gespeicherte Daten nach Keyword, Nische, Region und Verhältnis durchsuchen.
POST
https://api.shortsmonkey.com/v1/videos/outliers/search2 Credits pro tatsächlich zurückgegebenen 1–20 Einträgen
Outlier-Videosuche#
Gespeicherte Daten nach Keyword, Nische, Region und Verhältnis durchsuchen.
Authentifizierung#
Sende Authorization: Bearer sm_live_.... Der vollständige Schlüssel gehört nicht in URLs, Cookies, Bodies, Logs oder Analytics.
Datenaktualität#
Ranglisten lesen nur stabile Worker-Snapshots. Öffentliche Leseanfragen starten nie einen YouTube-Refresh.
Anfrage#
| Element | Wert | Beschreibung |
|---|---|---|
| Methode | POST | HTTP-Anfragemethode |
| Vollständige URL | https://api.shortsmonkey.com/v1/videos/outliers/search | Produktions-API-URL |
| Authentifizierung | Authorization: Bearer sm_live_... | Den vollständigen Schlüssel nur im Header senden |
| Inhaltstyp | application/json | Der Request-Body verwendet JSON |
| Credits | 2 Credits pro tatsächlich zurückgegebenen 1–20 Einträgen | Fehlerantworten kosten 0 Credits |
Anfrageparameter#
| Name | Position | Typ | Erforderlich | Standard | Werte oder Grenzen | Beschreibung |
|---|---|---|---|---|---|---|
keyword | JSON-Body | string | Nein | — | 1–120 Zeichen | Keyword für gespeicherte Titel- oder Nischentexte |
niche | JSON-Body | string | Nein | — | 1–80 Zeichen | Nischen- oder Kategoriefilter |
video_type | JSON-Body | string | Nein | all | shorts / long / all | Videotyp |
region | JSON-Body | string | Nein | — | 2–16 Zeichen | Regionscode |
max_channel_subscribers | JSON-Body | integer | Nein | — | 0–10,000,000 | Maximale Kanal-Abonnentenzahl |
min_views | JSON-Body | integer | Nein | — | 0–1,000,000,000 | Mindestanzahl der Aufrufe |
min_vs_ratio | JSON-Body | number | Nein | 10 | 0–100,000 | Minimales Verhältnis Aufrufe zu Abonnenten |
time_window | JSON-Body | string | Nein | 7d | 24h / 3d / 7d / 30d | Veröffentlichungszeitraum |
limit | JSON-Body | integer | Nein | 20 | 1–50 | Maximale Anzahl von Einträgen auf dieser Seite |
all_cursor | JSON-Body | string | Nein | — | data.all_data.next_cursor | Nächste ungefilterte Seite abrufen |
filter_cursor | JSON-Body | string | Nein | — | data.filter_data.next_cursor | Nächste gefilterte Seite ohne Filteränderung abrufen |
cursor | JSON-Body | string | Nein | — | Veralteter Kompatibilitätsparameter | Alias für filter_cursor; nicht beide senden |
Felder der Erfolgsantwort#
all_data ist eine ungefilterte Seite des stabilen Snapshots; filter_data stammt aus demselben Snapshot nach Standard- und Anfragefiltern. Beide Ergebnisse werden unabhängig paginiert.
Punktnotation kennzeichnet verschachtelte Objekte und [] Array-Elemente. Unbekannte Abonnentenzahlen sind null. Eine Anfrage wird einmal nach der größeren Ergebnismenge berechnet, nie nach der Summe.
| Feldpfad | Typ | Nullable | Beschreibung |
|---|---|---|---|
data.all_data.items | array<object> | Nein | Ungefilterte Videoelemente der aktuellen Seite |
data.all_data.items[].video_id | string | Nein | YouTube-Video-ID |
data.all_data.items[].title | string | Nein | Videotitel |
data.all_data.items[].video_url | string | Nein | YouTube-Video-URL |
data.all_data.items[].channel.id | string | Ja | Kanal-ID |
data.all_data.items[].channel.title | string | Nein | Kanalname |
data.all_data.items[].channel.subscribers | integer | Ja | Abonnentenzahl; bei Ausblendung null |
data.all_data.items[].channel.subscriber_count_hidden | boolean | Nein | Ob die Abonnentenzahl ausgeblendet ist |
data.all_data.items[].views | integer | Nein | Aufruf-Snapshot |
data.all_data.items[].views_to_subscribers_ratio | number | Ja | Verhältnis Aufrufe zu Abonnenten |
data.all_data.items[].opportunity_score | number | Ja | Opportunity-Score |
data.all_data.items[].duration_seconds | integer | Nein | Videodauer in Sekunden |
data.all_data.items[].published_at | string(date-time) | Ja | Videoveröffentlichung in UTC ISO 8601 |
data.all_data.items[].snapshot_at | string(date-time) | Ja | Zeitpunkt der Datenerfassung |
data.all_data.items[].niche | string | Ja | Nische oder Kategorie |
data.all_data.items[].track | string | Ja | Datensatz-Track |
data.all_data.items[].region | string | Ja | Regionscode |
data.all_data.items[].reasons | array<string> | Nein | Rankinggründe |
data.all_data.items[].video_type | string | Nein | shorts oder long |
data.all_data.next_cursor | string | Ja | Cursor der nächsten Seite für dieses Ergebnis; am Ende null |
data.filter_data.items | array<object> | Nein | Videoelemente nach Standard- und Anfragefiltern |
data.filter_data.items[].video_id | string | Nein | YouTube-Video-ID |
data.filter_data.items[].title | string | Nein | Videotitel |
data.filter_data.items[].video_url | string | Nein | YouTube-Video-URL |
data.filter_data.items[].channel.id | string | Ja | Kanal-ID |
data.filter_data.items[].channel.title | string | Nein | Kanalname |
data.filter_data.items[].channel.subscribers | integer | Ja | Abonnentenzahl; bei Ausblendung null |
data.filter_data.items[].channel.subscriber_count_hidden | boolean | Nein | Ob die Abonnentenzahl ausgeblendet ist |
data.filter_data.items[].views | integer | Nein | Aufruf-Snapshot |
data.filter_data.items[].views_to_subscribers_ratio | number | Ja | Verhältnis Aufrufe zu Abonnenten |
data.filter_data.items[].opportunity_score | number | Ja | Opportunity-Score |
data.filter_data.items[].duration_seconds | integer | Nein | Videodauer in Sekunden |
data.filter_data.items[].published_at | string(date-time) | Ja | Videoveröffentlichung in UTC ISO 8601 |
data.filter_data.items[].snapshot_at | string(date-time) | Ja | Zeitpunkt der Datenerfassung |
data.filter_data.items[].niche | string | Ja | Nische oder Kategorie |
data.filter_data.items[].track | string | Ja | Datensatz-Track |
data.filter_data.items[].region | string | Ja | Regionscode |
data.filter_data.items[].reasons | array<string> | Nein | Rankinggründe |
data.filter_data.items[].video_type | string | Nein | shorts oder long |
data.filter_data.next_cursor | string | Ja | Cursor der nächsten Seite für dieses Ergebnis; am Ende null |
meta.request_id | string | Nein | Anfrage-Trace-ID |
meta.snapshot_id | string | Nein | Stabile Snapshot-ID |
meta.snapshot_at | string(date-time) | Nein | Snapshot-Zeitpunkt |
meta.data_status | string | Nein | Datensatzstatus |
credits.cost | integer | Nein | Tatsächlich berechnete Credits |
credits.remaining | integer | Nein | Verbleibende Konto-Credits |
credits.period_ends_at | string(date-time) | Nein | Ende des aktuellen Credit-Zeitraums |
Cursor-Seiten#
all_data.next_cursor wird als all_cursor, filter_data.next_cursor als filter_cursor gesendet. Beide Cursor sind unabhängig, signiert, undurchsichtig und 24 Stunden gültig; cursor ist nur ein veralteter Alias für filter_cursor.
ETag#
Ranglisten unterstützen If-None-Match. HTTP 304 kostet 0 Credits.
Fehler und Limits#
Jeder Fehler enthält code, englische message, request_id und details. 4xx/5xx kosten 0 Credits.
| HTTP-Status | Code | Ursache | Empfehlung |
|---|---|---|---|
| 400 | INVALID_REQUEST | Ungültiges Parameterformat, Kombination oder Bereich | Parameter anhand von details.issues korrigieren |
| 401 | INVALID_API_KEY | Der Schlüssel ist ungültig oder inaktiv | Bearer-Header und Schlüsselstatus prüfen |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | Abonnement oder Credits sind nicht verfügbar | Tarif, Guthaben und Schlüsselbudget prüfen |
| 429 | RATE_LIMITED | Rate- oder Parallelitätslimit überschritten | Nach Retry-After erneut versuchen |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | Daten oder Dienst sind vorübergehend nicht verfügbar | Später erneut versuchen und request_id aufbewahren |
curl -X POST "https://api.shortsmonkey.com/v1/videos/outliers/search" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword":"finance","video_type":"all","time_window":"7d","min_vs_ratio":10,"limit":20}'