Docs menu

GDELT API endpoint

GDELT Television Visual Entities API

Lists the computer-vision object and activity labels GDELT recognises in US television video, most frequent first, up to `limit` entries (default 100, max 10000). The label itself is the value to pass as `visual` to the GDELT TV search and chart endpoints. The list does not depend on any query.

GETapiKey0 credits/requestGDELTgdelt.tvVisualEntityDetailsResponseDoc/gdelt/tv-visual-entities

Endpoint facts

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

GDELT News Monitoring API Try GDELT Television Visual Entities API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

limit (optional) — maximum entries to return, most-frequent first. Default 100, maximum 10000.

Notable response behavior:

entities is query-independent — the same list every call returns, regardless of any other GDELT endpoint's query/station/time-range state. Only limit changes what comes back.
entities[].label is the exact string to pass as visual on gdelt-tv-search/gdelt-tv-timeline/gdelt-tv-stationchart/gdelt-tv-showchart — unlike gdelt-tv-concept-entities's mid/label pair, visual labels have no separate code; the label itself is the search value.
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
Cached for longer (a few hours) than the rest of this platform, since this is reference data that only shifts as GDELT's own recognized visual vocabulary grows.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tv-visual-entities?limit=40
Items in entities: 40
Fields filled in every checked item: 1

Field	Filled in, of 40 checked	Values in the sample
label	40	“person” and 39 other values

Request parameters

Parameter	Type	Required	Default	Description	Example
limit	integer	No		Maximum entries to return, most-frequent first. Minimum: 1. Maximum: 10000.
x-api-key (header)	string	Yes		API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-visual-entities?limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=visualentitydetails&maxrecords=100",
    "fetched_at": "2026-08-20T10:00:00Z",
    "entities": [
      {
        "label": "person"
      },
      {
        "label": "snapshot"
      },
      {
        "label": "photograph"
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvVisualEntityDetailsResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TVVisualEntityDetailsResponse	No
data.entities	array	No
data.entities[].label	string	No	person
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=visualentitydetails&maxrecords=100
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-visual-entities?limit=10" \
  -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 Visual Entities API

GETapiKey0 credits/requestGDELTgdelt.tvVisualEntityDetailsResponseDoc/gdelt/tv-visual-entities

Endpoint facts

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

GDELT News Monitoring API Try GDELT Television Visual Entities API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

limit (optional) — maximum entries to return, most-frequent first. Default 100, maximum 10000.

Notable response behavior:

entities is query-independent — the same list every call returns, regardless of any other GDELT endpoint's query/station/time-range state. Only limit changes what comes back.
entities[].label is the exact string to pass as visual on gdelt-tv-search/gdelt-tv-timeline/gdelt-tv-stationchart/gdelt-tv-showchart — unlike gdelt-tv-concept-entities's mid/label pair, visual labels have no separate code; the label itself is the search value.
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
Cached for longer (a few hours) than the rest of this platform, since this is reference data that only shifts as GDELT's own recognized visual vocabulary grows.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tv-visual-entities?limit=40
Items in entities: 40
Fields filled in every checked item: 1

Field	Filled in, of 40 checked	Values in the sample
label	40	“person” and 39 other values

Request parameters

Parameter	Type	Required	Default	Description	Example
limit	integer	No		Maximum entries to return, most-frequent first. Minimum: 1. Maximum: 10000.
x-api-key (header)	string	Yes		API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-visual-entities?limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=visualentitydetails&maxrecords=100",
    "fetched_at": "2026-08-20T10:00:00Z",
    "entities": [
      {
        "label": "person"
      },
      {
        "label": "snapshot"
      },
      {
        "label": "photograph"
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvVisualEntityDetailsResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TVVisualEntityDetailsResponse	No
data.entities	array	No
data.entities[].label	string	No	person
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=visualentitydetails&maxrecords=100
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-visual-entities?limit=10" \
  -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 Visual Entities 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 Visual Entities API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related