Docs menu

GDELT API endpoint

GDELT Television Search API

Searches GDELT's US television news index on one required `station` (`CNN`, `MSNBC`, `FOXNEWS`, `BBCNEWS`, `KGO`, `KPIX` or `KNTV`). Match on `transcript`, `caption`, `concept`, `onscreen_text` or `visual`, with matching `exclude_` options. Returns up to `maxrecords` clips (default 50, max 3000) with show, station, timing, caption, transcript, onscreen text and clip URL. Results lag 24 to 48 hours.

GETapiKey0 credits/requestGDELTgdelt.tvSearchResponseDoc/gdelt/tv-search

Endpoint facts

Method: GET
API path: /gdelt/tv-search
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.tvSearchResponseDoc

GDELT News Monitoring API Try GDELT Television Search API in Playground GDELT API documentation

How this endpoint behaves

Narrower coverage than gdelt-search/ gdelt-context: 4 US TV stations only, not global multilingual text, and results carry a 24-48 hour processing delay — treat this endpoint as slower-moving than the rest of the platform. Availability is otherwise best-effort, as for gdelt-search; see gdelt-search's description for the full availability and attribution notes.

Path parameters:

None.

Query parameters:

transcript (optional, repeatable) — search machine-generated speech-to-text transcripts (GDELT's asr: operator). Multiple values are OR'd together. Short phrases only — GDELT caps each at 5 words.
caption (optional, repeatable) — search human-provided closed captioning (GDELT's cap: operator). Multiple values are OR'd together.
concept (optional, repeatable) — search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator), e.g. /M/0d063v. Multiple values are OR'd together. See gdelt-tv-concept-entities for GDELT's own catalog of valid MID codes.
onscreen_text (optional, repeatable) — search OCR'd onscreen text/chyrons (GDELT's ocr: operator). Multiple values are OR'd together. Short phrases only — GDELT caps each at 5 words.
visual (optional, repeatable) — search visual object/activity labels from computer vision (GDELT's visual: operator), e.g. VOLCANO, POLICE. Multiple values are OR'd together. See gdelt-tv-visual-entities for GDELT's own catalog of valid labels.
exclude_transcript (optional, repeatable) — exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Every value must be absent.
exclude_caption (optional, repeatable) — exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Every value must be absent.
exclude_concept (optional, repeatable) — exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Every value must be absent.
exclude_onscreen_text (optional, repeatable) — exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Every value must be absent.
exclude_visual (optional, repeatable) — exclude clips whose visual labels match this value (GDELT's -visual: operator). Every value must be absent.
station (required) — station to search. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO (ABC, San Francisco), KPIX (CBS, San Francisco), KNTV (NBC, San Francisco). GDELT rejects any request with no station. See gdelt-tv-stationdetails for GDELT's own current list and each station's coverage window.
show (optional) — limit to an exact show name.
day_of_week (optional) — limit to a day of week, 0 (Sunday) through 7 (Saturday), PST.
timespan (optional) — relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. GDELT's TV archive starts July 6, 2010.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to (optional) — end of an absolute time window. Same formats as from.
sort (optional, default relevance) — result order. Allowed values: relevance, datedesc, dateasc.
maxrecords (optional, default 50) — rows to return. GDELT's own hard cap here is 3000.

At least one of transcript/caption/concept/onscreen_text/visual is expected to actually find anything — a station-only (or station+show) browse with no content operator is not rejected client-side, but is unlikely to be a meaningful query. An exclude_* value does not count as that positive term — GDELT rejects a query built from exclude_* fields alone ("Queries must have at least one non-negative term."); combine exclusion with at least one non-exclude_* field.

Notable response behavior:

matched_at is the exact timestamp of the matched moment within the broadcast; show_start_at is when the containing show began.
visual_entities is returned as a list.
count is the number of clips actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error).
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
A GDELT-side rate limit, an all-too-common ASR/caption/OCR phrase, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tv-search?caption=climate&station=CNN
Items in clips: 50
Fields filled in every checked item: 8
Fields empty in some or all items: 3

Field	Filled in, of 50 checked	Values in the sample
station	50	cnn in all 50
show	50	“Inside Politics” and 32 other values
show_start_at	50	2011-06-02 to 2024-09-07
matched_at	50	2011-06-02 to 2024-09-07
transcript	50	“climate change the” and 23 other values
caption	50	“climate” and 13 other values
onscreen_text	48	median 142 characters
visual_entities	49	median 22 entries
clip_url	50	archive.org
thumbnail_url	50	data.gdeltproject.org
caption_concepts	6	“u.s.” and 5 other values

Request parameters

Parameter	Type	Required	Description	Example
transcript	array<string>	No	Search machine-generated speech-to-text transcripts (GDELT's asr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	climate change
caption	array<string>	No	Search human-provided closed captioning (GDELT's cap: operator). Repeatable; multiple values are OR'd together.	climate change
concept	array<string>	No	Search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator). Repeatable; multiple values are OR'd together.	/M/0d063v
onscreen_text	array<string>	No	Search OCR'd onscreen text/chyrons (GDELT's ocr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	breaking news
visual	array<string>	No	Search visual object/activity labels from computer vision (GDELT's visual: operator). Repeatable; multiple values are OR'd together.	flood
exclude_transcript	array<string>	No	Exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Repeatable; every value must be absent.	campaign ad
exclude_caption	array<string>	No	Exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Repeatable; every value must be absent.	sanders
exclude_concept	array<string>	No	Exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Repeatable; every value must be absent.	/M/081pw
exclude_onscreen_text	array<string>	No	Exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Repeatable; every value must be absent.	sponsored
exclude_visual	array<string>	No	Exclude clips whose visual labels match this value (GDELT's -visual: operator). Repeatable; every value must be absent.	advertisement
station	string	Yes	Station to search. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO, KPIX, KNTV.	CNN
show	string	No	Limit to an exact show name.	Inside Politics
day_of_week	integer	No	Limit to a day of week, 0 (Sunday) through 7 (Saturday), PST. Minimum: 0. Maximum: 7.
timespan	string	No	Relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. GDELT's TV archive starts July 6, 2010.	7d
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
sort	string	No	Result order. Allowed values: relevance, datedesc, dateasc.
maxrecords	integer	No	Rows to return. GDELT's own hard cap is 3000 for this endpoint; there is no pagination cursor beyond it. Minimum: 1. Maximum: 3000.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-search?station=CNN&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "cap:\"climate change\" station:CNN",
    "station": "CNN",
    "sort": "relevance",
    "maxrecords": 50,
    "count": 1,
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&maxrecords=50&mode=clipgallery&query=cap%3A%22climate+change%22+station%3ACNN",
    "fetched_at": "2026-08-20T10:00:00Z",
    "clips": [
      {
        "station": "cnn",
        "show": "Inside Politics",
        "show_start_at": "2019-05-03T16:00:00Z",
        "matched_at": "2019-05-03T17:00:56Z",
        "transcript": "climate change the",
        "caption": "climate",
        "onscreen_text": "SWEEPING PLAN LIVE",
        "visual_entities": [
          "person",
          "news",
          "facial expression"
        ],
        "clip_url": "https://archive.org/details/CNNW_20190503_160000_Inside_Politics/start/3656",
        "thumbnail_url": "http://data.gdeltproject.org/televisionexplorer/thumbnails/CNNW_20190503_160000_Inside_Politics-003656.jpg"
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvSearchResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TVClipSearchResponse	No
data.clips	array	No
data.clips[].caption	string	No	climate
data.clips[].caption_concepts	string	No	/M/0d063v
data.clips[].clip_url	string	No	https://archive.org/details/CNNW_20190503_160000_Inside_Politics/start/3656
data.clips[].matched_at	string	No	2019-05-03T17:00:56Z
data.clips[].onscreen_text	string	No	BREAKING NEWS: SEA LEVELS RISING
data.clips[].show	string	No	Inside Politics
data.clips[].show_start_at	string	No	2019-05-03T16:00:00Z
data.clips[].station	string	No	cnn
data.clips[].thumbnail_url	string	No	http://data.gdeltproject.org/televisionexplorer/thumbnails/CNNW_20190503_160000_Inside_Politics-003656.jpg
data.clips[].transcript	string	No	climate change the
data.clips[].visual_entities	array	No	person,news,weather
data.count	integer	No	3
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.maxrecords	integer	No	50
data.query	string	No	cap:"climate change" station:CNN
data.sort	string	No	relevance
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&maxrecords=50&mode=clipgallery&query=cap%3A%22climate+change%22+station%3ACNN
data.station	string	No	CNN
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-search?station=CNN&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More GDELT endpoint docs GDELT News Monitoring API GDELT Context Search API documentation GDELT Search API documentation GDELT Timeline API documentation GDELT Tone Chart API documentation GDELT Television Concept Entities API documentation GDELT Television Show Chart API documentation

Open in Playground Back to group

Docs menu

GDELT API endpoint

GDELT Television Search API

GETapiKey0 credits/requestGDELTgdelt.tvSearchResponseDoc/gdelt/tv-search

Endpoint facts

Method: GET
API path: /gdelt/tv-search
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.tvSearchResponseDoc

GDELT News Monitoring API Try GDELT Television Search API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

transcript (optional, repeatable) — search machine-generated speech-to-text transcripts (GDELT's asr: operator). Multiple values are OR'd together. Short phrases only — GDELT caps each at 5 words.
caption (optional, repeatable) — search human-provided closed captioning (GDELT's cap: operator). Multiple values are OR'd together.
concept (optional, repeatable) — search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator), e.g. /M/0d063v. Multiple values are OR'd together. See gdelt-tv-concept-entities for GDELT's own catalog of valid MID codes.
onscreen_text (optional, repeatable) — search OCR'd onscreen text/chyrons (GDELT's ocr: operator). Multiple values are OR'd together. Short phrases only — GDELT caps each at 5 words.
visual (optional, repeatable) — search visual object/activity labels from computer vision (GDELT's visual: operator), e.g. VOLCANO, POLICE. Multiple values are OR'd together. See gdelt-tv-visual-entities for GDELT's own catalog of valid labels.
exclude_transcript (optional, repeatable) — exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Every value must be absent.
exclude_caption (optional, repeatable) — exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Every value must be absent.
exclude_concept (optional, repeatable) — exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Every value must be absent.
exclude_onscreen_text (optional, repeatable) — exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Every value must be absent.
exclude_visual (optional, repeatable) — exclude clips whose visual labels match this value (GDELT's -visual: operator). Every value must be absent.
station (required) — station to search. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO (ABC, San Francisco), KPIX (CBS, San Francisco), KNTV (NBC, San Francisco). GDELT rejects any request with no station. See gdelt-tv-stationdetails for GDELT's own current list and each station's coverage window.
show (optional) — limit to an exact show name.
day_of_week (optional) — limit to a day of week, 0 (Sunday) through 7 (Saturday), PST.
timespan (optional) — relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. GDELT's TV archive starts July 6, 2010.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to (optional) — end of an absolute time window. Same formats as from.
sort (optional, default relevance) — result order. Allowed values: relevance, datedesc, dateasc.
maxrecords (optional, default 50) — rows to return. GDELT's own hard cap here is 3000.

Notable response behavior:

matched_at is the exact timestamp of the matched moment within the broadcast; show_start_at is when the containing show began.
visual_entities is returned as a list.
count is the number of clips actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error).
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
A GDELT-side rate limit, an all-too-common ASR/caption/OCR phrase, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tv-search?caption=climate&station=CNN
Items in clips: 50
Fields filled in every checked item: 8
Fields empty in some or all items: 3

Field	Filled in, of 50 checked	Values in the sample
station	50	cnn in all 50
show	50	“Inside Politics” and 32 other values
show_start_at	50	2011-06-02 to 2024-09-07
matched_at	50	2011-06-02 to 2024-09-07
transcript	50	“climate change the” and 23 other values
caption	50	“climate” and 13 other values
onscreen_text	48	median 142 characters
visual_entities	49	median 22 entries
clip_url	50	archive.org
thumbnail_url	50	data.gdeltproject.org
caption_concepts	6	“u.s.” and 5 other values

Request parameters

Parameter	Type	Required	Description	Example
transcript	array<string>	No	Search machine-generated speech-to-text transcripts (GDELT's asr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	climate change
caption	array<string>	No	Search human-provided closed captioning (GDELT's cap: operator). Repeatable; multiple values are OR'd together.	climate change
concept	array<string>	No	Search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator). Repeatable; multiple values are OR'd together.	/M/0d063v
onscreen_text	array<string>	No	Search OCR'd onscreen text/chyrons (GDELT's ocr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	breaking news
visual	array<string>	No	Search visual object/activity labels from computer vision (GDELT's visual: operator). Repeatable; multiple values are OR'd together.	flood
exclude_transcript	array<string>	No	Exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Repeatable; every value must be absent.	campaign ad
exclude_caption	array<string>	No	Exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Repeatable; every value must be absent.	sanders
exclude_concept	array<string>	No	Exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Repeatable; every value must be absent.	/M/081pw
exclude_onscreen_text	array<string>	No	Exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Repeatable; every value must be absent.	sponsored
exclude_visual	array<string>	No	Exclude clips whose visual labels match this value (GDELT's -visual: operator). Repeatable; every value must be absent.	advertisement
station	string	Yes	Station to search. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO, KPIX, KNTV.	CNN
show	string	No	Limit to an exact show name.	Inside Politics
day_of_week	integer	No	Limit to a day of week, 0 (Sunday) through 7 (Saturday), PST. Minimum: 0. Maximum: 7.
timespan	string	No	Relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. GDELT's TV archive starts July 6, 2010.	7d
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
sort	string	No	Result order. Allowed values: relevance, datedesc, dateasc.
maxrecords	integer	No	Rows to return. GDELT's own hard cap is 3000 for this endpoint; there is no pagination cursor beyond it. Minimum: 1. Maximum: 3000.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-search?station=CNN&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "cap:\"climate change\" station:CNN",
    "station": "CNN",
    "sort": "relevance",
    "maxrecords": 50,
    "count": 1,
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&maxrecords=50&mode=clipgallery&query=cap%3A%22climate+change%22+station%3ACNN",
    "fetched_at": "2026-08-20T10:00:00Z",
    "clips": [
      {
        "station": "cnn",
        "show": "Inside Politics",
        "show_start_at": "2019-05-03T16:00:00Z",
        "matched_at": "2019-05-03T17:00:56Z",
        "transcript": "climate change the",
        "caption": "climate",
        "onscreen_text": "SWEEPING PLAN LIVE",
        "visual_entities": [
          "person",
          "news",
          "facial expression"
        ],
        "clip_url": "https://archive.org/details/CNNW_20190503_160000_Inside_Politics/start/3656",
        "thumbnail_url": "http://data.gdeltproject.org/televisionexplorer/thumbnails/CNNW_20190503_160000_Inside_Politics-003656.jpg"
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvSearchResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TVClipSearchResponse	No
data.clips	array	No
data.clips[].caption	string	No	climate
data.clips[].caption_concepts	string	No	/M/0d063v
data.clips[].clip_url	string	No	https://archive.org/details/CNNW_20190503_160000_Inside_Politics/start/3656
data.clips[].matched_at	string	No	2019-05-03T17:00:56Z
data.clips[].onscreen_text	string	No	BREAKING NEWS: SEA LEVELS RISING
data.clips[].show	string	No	Inside Politics
data.clips[].show_start_at	string	No	2019-05-03T16:00:00Z
data.clips[].station	string	No	cnn
data.clips[].thumbnail_url	string	No	http://data.gdeltproject.org/televisionexplorer/thumbnails/CNNW_20190503_160000_Inside_Politics-003656.jpg
data.clips[].transcript	string	No	climate change the
data.clips[].visual_entities	array	No	person,news,weather
data.count	integer	No	3
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.maxrecords	integer	No	50
data.query	string	No	cap:"climate change" station:CNN
data.sort	string	No	relevance
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&maxrecords=50&mode=clipgallery&query=cap%3A%22climate+change%22+station%3ACNN
data.station	string	No	CNN
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-search?station=CNN&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

GDELT Television Search API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

GDELT Television Search API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related