BrowsableSend Authorization: Bearer YOUR_API_KEY. Get an API key →
Parameters
Send these fields in a flat JSON body. Add _run to choose execution options.
urlstringRequiredURL returned by the matching search endpoint. Minimum length: 1. Maximum length: 2000.
Response
Every response describes a run. Read result once run_status is succeeded.
run_id- The run to track. Keep it when contacting support.
run_status- Queued, running, waiting for sign-in, succeeded, or failed. Check this even after an HTTP 200.
status_url- Poll this URL while the run is pending. Keep the same run instead of starting another request.
result- The endpoint’s returned data. The example is illustrative; actual fields may be empty or unavailable.
error- On failure, inspect its code, message, retryable and action fields.
View the complete output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"success",
"source",
"query",
"url",
"results",
"count",
"data",
"max_results_requested",
"pagination"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"data": {
"type": "object",
"required": [
"id",
"type",
"slug",
"title",
"full_title",
"original_title",
"year",
"release_date",
"url",
"film_id",
"uid",
"letterboxd_id",
"tmdb_id",
"tmdb_type",
"imdb_id",
"external_urls",
"description",
"tagline",
"runtime_minutes",
"duration",
"genres",
"countries",
"languages",
"language_codes",
"directors",
"director_names",
"cast",
"cast_names",
"crew",
"image_url",
"image_urls",
"poster_images",
"stats",
"ratings",
"popular_reviews"
],
"properties": {
"id": {
"type": "string"
},
"uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string"
},
"cast": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
},
"crew": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"slug": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"const": "film"
},
"year": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"stats": {
"type": "object",
"properties": {
"like_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"list_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"watched_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"genres": {
"type": "array",
"items": {
"type": "string"
}
},
"film_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"imdb_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ratings": {
"type": "object",
"required": [
"count",
"calculated_average",
"distribution"
],
"properties": {
"count": {
"type": "integer"
},
"distribution": {
"type": "array",
"items": {
"type": "object",
"required": [
"rating",
"label",
"count",
"percentage"
],
"properties": {
"count": {
"type": "integer"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rating": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"percentage": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"calculated_average": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"tagline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tmdb_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"duration": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"countries": {
"type": "array",
"items": {
"type": "string"
}
},
"directors": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
},
"image_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"languages": {
"type": "array",
"items": {
"type": "string"
}
},
"tmdb_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cast_names": {
"type": "array",
"items": {
"type": "string"
}
},
"full_title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"image_urls": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"release_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"external_urls": {
"type": "object",
"required": [
"imdb",
"tmdb"
],
"properties": {
"imdb": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tmdb": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"letterboxd_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"poster_images": {
"type": "object",
"required": [
"small",
"medium",
"large"
],
"properties": {
"large": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"small": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"director_names": {
"type": "array",
"items": {
"type": "string"
}
},
"language_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"original_title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"popular_reviews": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"reviewer_name",
"reviewer_username",
"url",
"rating",
"rating_label",
"text",
"like_count"
],
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rating": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"like_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"rating_label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reviewer_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reviewer_username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"runtime_minutes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"count": {
"type": "integer"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"const": "letterboxd-film"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"type",
"slug",
"title",
"full_title",
"year",
"url",
"film_id",
"image_url"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"slug": {
"type": "string"
},
"type": {
"const": "film"
},
"year": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"film_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"image_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"full_title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"success": {
"const": true
},
"pagination": {
"type": "object",
"required": [
"cursor",
"next_cursor",
"has_next_page",
"count",
"strategy"
],
"properties": {
"count": {
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_next_page": {
"type": "boolean"
}
},
"additionalProperties": false
},
"max_results_requested": {
"type": "integer"
}
},
"additionalProperties": false
}View a polled run response
{
"run_id": "00000000-0000-4000-8000-000000000001",
"task_key": "letterboxd-film",
"task_name": "Letterboxd Film API",
"run_status": "succeeded",
"status_url": "/v1/runs/00000000-0000-4000-8000-000000000001",
"result": {
"url": "https://example.com/item-1",
"data": {
"id": "id-1",
"uid": "id-1",
"url": "https://example.com/item-1",
"cast": [
{
"url": "https://example.com/item-1",
"name": "Stylish Shoreditch Loft with Balcony"
}
],
"crew": {},
"slug": "sample",
"type": "film",
"year": 1,
"stats": {
"like_count": 1,
"list_count": 1,
"watched_count": 1
},
"title": "Stylish Shoreditch Loft with Balcony",
"genres": [
"sample"
],
"film_id": 1,
"imdb_id": "id-1",
"ratings": {
"count": 1,
"distribution": [
{
"count": 1,
"label": "Stylish Shoreditch Loft with Balcony",
"rating": 4.91,
"percentage": 1.5
}
],
"calculated_average": 51.5074
},
"tagline": "Featured",
"tmdb_id": 1,
"duration": "sample",
"countries": [
"sample"
],
"directors": [
{
"url": "https://example.com/item-1",
"name": "Stylish Shoreditch Loft with Balcony"
}
],
"image_url": "https://example.com/item-1",
"languages": [
"sample"
],
"tmdb_type": "sample",
"cast_names": [
"Stylish Shoreditch Loft with Balcony"
],
"full_title": "Stylish Shoreditch Loft with Balcony",
"image_urls": [
"https://images.example.com/image_urls-1.jpg"
],
"description": "Sample description 1",
"release_date": "sample",
"external_urls": {
"imdb": "sample",
"tmdb": "sample"
},
"letterboxd_id": "id-1",
"poster_images": {
"large": "sample",
"small": "sample",
"medium": "sample"
},
"director_names": [
"Stylish Shoreditch Loft with Balcony"
],
"language_codes": [
"sample"
],
"original_title": "Stylish Shoreditch Loft with Balcony",
"popular_reviews": [
{
"id": "id-1",
"url": "https://example.com/item-1",
"text": "Sample text 1",
"rating": 4.91,
"like_count": 1,
"rating_label": "Stylish Shoreditch Loft with Balcony",
"reviewer_name": "Stylish Shoreditch Loft with Balcony",
"reviewer_username": "Stylish Shoreditch Loft with Balcony"
}
],
"runtime_minutes": 1.5
},
"count": 1,
"query": "London",
"source": "letterboxd-film",
"results": [
{
"id": "id-1",
"url": "https://example.com/item-1",
"slug": "sample",
"type": "film",
"year": 1,
"title": "Stylish Shoreditch Loft with Balcony",
"film_id": 1,
"image_url": "https://example.com/item-1",
"full_title": "Stylish Shoreditch Loft with Balcony"
}
],
"success": true,
"pagination": {
"count": 1,
"cursor": "cursor-page-1",
"strategy": "sample",
"next_cursor": "cursor-page-1",
"has_next_page": true
},
"max_results_requested": 1
},
"error": null
}Errors & retries
400Fix the fields listed inerrorsbefore retrying.428Connect the requested website account using the returned sign-in link.429Wait for the duration inRetry-After.5xxRetry transient failures with backoff. Keep the request ID.
A failed run has its own error inside the response. Retry it only when error.retryable is true.
More examples
Async request with polling
RUN=$(curl -s -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/letterboxd/film" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://letterboxd.com/film/parasite-2019/"}')
RUN_ID=$(echo "$RUN" | jq -er '.run_id // empty') || { echo "$RUN" >&2; exit 1; }
POLL_DELAY=3
while true; do
RESULT=$(curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/runs/$RUN_ID")
STATUS=$(echo "$RESULT" | jq -r '.run_status')
if [[ "$STATUS" =~ ^(succeeded|failed|errored|cancelled|canceled|expired)$ ]]; then
echo "$RESULT"
break
fi
sleep "$(awk "BEGIN { print $POLL_DELAY * (0.9 + ($RANDOM % 21) / 100) }")"
POLL_DELAY=$((POLL_DELAY < 30 ? POLL_DELAY * 2 : 30))
[ "$POLL_DELAY" -gt 30 ] && POLL_DELAY=30
doneWait-for-results request
curl -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/letterboxd/film" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://letterboxd.com/film/parasite-2019/","_run":{"async":false}}'Canonical & compatibility routes
You can also send the same JSON body to /v1/tasks/letterboxd-film/runs.