Docs menu

GDELT API endpoint

GDELT Television Timeline API

Returns the amount of US television news airtime matching the supplied query over time, using GDELT Television 2.0 AI timeline-volume data. A station is required. Supports the same caption, transcript, concept, and visual match operators as gdelt-tv-search; coverage and processing-delay caveats are documented there.

GETapiKey0 credits/requestGDELTgdelt.tvTimelineResponseDoc/gdelt/tv-timeline

Endpoint facts

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

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

How this endpoint behaves

Return how much airtime a query's matching US television news coverage occupied over time (GDELT's Television 2.0 AI mode=timelinevol), for a required station. Same match-channel operators as gdelt-tv-search; see that endpoint's description for the same coverage (4 US stations only) and staleness (24-48 hour processing delay) caveats.

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.
timespan (optional) — relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. Omit both for GDELT's full archive at auto-selected resolution (back to 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.

An exclude_* value does not count as a positive term — GDELT rejects a query built from station/exclude_* fields alone ("Queries must have at least one non-negative term."); combine exclusion with at least one non-exclude_* content field.

Notable response behavior:

series normally contains exactly one entry; GDELT's Television 2.0 AI timeline doesn't name its series the way DOC 2.0's does (the series field is empty), but points is still chronologically ordered.
GDELT auto-selects a date resolution (hour/day/week/month/year) based on the requested window's length; there is no smooth parameter for this endpoint (unlike gdelt-timeline).
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
A GDELT-side rate limit, 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-timeline?caption=trump&station=CNN&timespan=30d
Fields returned with a value: 2
Fields returned empty: 1

Field	In the sample
query	Has a value
station	Has a value
series	Empty

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
timespan	string	No	Relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. Omit both for GDELT's full archive (auto-resolution, back to July 6, 2010).	30d
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-07-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
x-api-key (header)	string	Yes	API key required

cURL example

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

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "cap:\"trump\" station:CNN",
    "station": "CNN",
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?enddatetime=20220831000000&format=json&mode=timelinevol&query=cap%3A%22trump%22+station%3ACNN&startdatetime=20220801000000",
    "fetched_at": "2026-08-20T10:00:00Z",
    "series": [
      {
        "series": "",
        "points": [
          {
            "date": "2022-08-01T12:00:00Z",
            "value": 76
          },
          {
            "date": "2022-08-02T12:00:00Z",
            "value": 170
          }
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvTimelineResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	gdelt.TVTimelineResponse	No
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.query	string	No	cap:"climate change" station:CNN
data.series	array	No		TimelineSeries record, 4 fields: points, series. Described under GDELT Timeline API.
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=timelinevol&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-timeline?station=CNN" \
  -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 Search API documentation

Open in Playground Back to group

Docs menu

GDELT API endpoint

GDELT Television Timeline API

GETapiKey0 credits/requestGDELTgdelt.tvTimelineResponseDoc/gdelt/tv-timeline

Endpoint facts

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

GDELT News Monitoring API Try GDELT Television Timeline 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.
timespan (optional) — relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. Omit both for GDELT's full archive at auto-selected resolution (back to 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.

Notable response behavior:

series normally contains exactly one entry; GDELT's Television 2.0 AI timeline doesn't name its series the way DOC 2.0's does (the series field is empty), but points is still chronologically ordered.
GDELT auto-selects a date resolution (hour/day/week/month/year) based on the requested window's length; there is no smooth parameter for this endpoint (unlike gdelt-timeline).
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
A GDELT-side rate limit, 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-timeline?caption=trump&station=CNN&timespan=30d
Fields returned with a value: 2
Fields returned empty: 1

Field	In the sample
query	Has a value
station	Has a value
series	Empty

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
timespan	string	No	Relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. Omit both for GDELT's full archive (auto-resolution, back to July 6, 2010).	30d
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-07-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
x-api-key (header)	string	Yes	API key required

cURL example

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

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "cap:\"trump\" station:CNN",
    "station": "CNN",
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?enddatetime=20220831000000&format=json&mode=timelinevol&query=cap%3A%22trump%22+station%3ACNN&startdatetime=20220801000000",
    "fetched_at": "2026-08-20T10:00:00Z",
    "series": [
      {
        "series": "",
        "points": [
          {
            "date": "2022-08-01T12:00:00Z",
            "value": 76
          },
          {
            "date": "2022-08-02T12:00:00Z",
            "value": 170
          }
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvTimelineResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	gdelt.TVTimelineResponse	No
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.query	string	No	cap:"climate change" station:CNN
data.series	array	No		TimelineSeries record, 4 fields: points, series. Described under GDELT Timeline API.
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=timelinevol&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-timeline?station=CNN" \
  -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 Timeline 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 Timeline API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related