What Does a Film Festival Actually Screen? Measure Festival Fit with Programming Profiles

A festival listing tells you what organizers say they accept. A programming profile tells you what they have actually screened and awarded. That difference matters when you are deciding whether a festival fits your film, building a submission shortlist for a client, or comparing programming patterns across hundreds of events.

Festival API's new Programming Profiles endpoint turns a festival's historical roster into a compact, evidence-based summary. One request shows the categories that dominate its program, the years represented in the data, recurring award categories, documentary and animation shares, data coverage, and a confidence rating. You can assess festival fit without downloading every roster record and rebuilding the analysis yourself.

What is a festival programming profile?

A festival programming profile is an analysis of films associated with a festival's historical roster. It answers a more useful version of the question "What films does this festival screen?" by counting what appears in the record rather than relying only on category labels or promotional copy.

Call the endpoint with a Festival API festival ID:

GET https://festivalapi.com/v1/festivals/{id}/programming-profile/

The request costs 5 credits. The response includes:

• sample_size, years_analyzed, year_distribution, and year_range to show how much history supports the profile.
• dominant_categories with a count and share for each identified category.
• common_award_categories and award_winners to expose award patterns and specific examples.
• programming_trends for documentary, animation, experimental, and music-video representation when those categories appear.
• director_coverage and genre_coverage so you can see which parts of the roster are complete enough to use.
• confidence and last_verified_at to describe reliability and freshness.

Profiles refresh automatically when a festival's roster changes. You do not need to maintain a separate refresh schedule or decide when an old profile has become stale.

A real example: AFRIFF's programming history

The live profile for the Africa International Film Festival (AFRIFF), festival ID 2629, was built from 85 roster entries spanning records from 2021, 2023, 2024, and 2025. The excerpt below is shortened for readability but keeps the values returned by the API:

{
  "festival_id": 2629,
  "festival_name": "Africa International Film Festival (AFRIFF)",
  "sample_size": 85,
  "years_analyzed_count": 4,
  "years_analyzed": [2021, 2023, 2024, 2025],
  "year_range": {"min": 2021, "max": 2025},
  "year_distribution": [
    {"year": 2021, "count": 1},
    {"year": 2023, "count": 2},
    {"year": 2024, "count": 27},
    {"year": 2025, "count": 52}
  ],
  "dominant_categories": [
    {"category": "short", "count": 43, "share": 0.5059},
    {"category": "feature", "count": 18, "share": 0.2118},
    {"category": "documentary", "count": 14, "share": 0.1647},
    {"category": "animation", "count": 5, "share": 0.0588},
    {"category": "student", "count": 5, "share": 0.0588}
  ],
  "programming_trends": [
    {"trend": "Documentary", "category": "documentary", "count": 14, "share": 0.1647},
    {"trend": "Animation", "category": "animation", "count": 5, "share": 0.0588}
  ],
  "director_coverage": {"ratio": 1.0, "populated_rows": 85},
  "genre_coverage": {
    "ratio": 0.0,
    "populated_rows": 0,
    "notes": "Genre tags are sparse in current roster data."
  },
  "runtime_analysis": null,
  "production_country_distribution": null,
  "confidence": "very_high",
  "last_verified_at": "2026-08-11T17:55:06.314060+00:00"
}

The category shares give a filmmaker a quick read on the program. Shorts account for 50.59% of the analyzed roster, while features account for 21.18%. Documentary titles represent 16.47%. That does not predict whether a new film will be selected, but it provides stronger evidence than a broad "all genres welcome" statement.

The coverage fields prevent false precision. AFRIFF's profile has director data for all 85 records, but no populated genre tags in this sample. A recommendation tool can use director and category evidence while declining to make a genre-level claim.

How filmmakers can use the profile

For a filmmaker planning a documentary festival submission campaign, the documentary share is useful context, not an automatic score. A 16.47% share tells you that documentary work has a visible place in this program. The award data can add another layer: AFRIFF's response includes categories such as Best Documentary Short and Best International Documentary, plus named award-winning films.

Use the profile alongside the festival detail record. The detail endpoint helps you check current deadlines, fees, location, and submission links. The programming profile helps you judge historical fit. Together, those records support a shortlist based on both practical eligibility and observed programming.

A simple review process could be:

1. Filter festivals by category, country, deadline, and budget.
2. Request programming profiles for the strongest candidates.
3. Compare category shares, award patterns, sample size, and confidence.
4. Read the underlying roster when a profile shows a promising match that needs human review.

Keep editorial judgment in the process. A festival may be changing direction, launching a new strand, or looking for work unlike its recent selections. The profile describes history. It does not claim to know the next jury's choices.

How curators and data teams can use it

Programming Profiles also reduce the work required to build festival research products. A data team can store the normalized response, compare category concentration across festivals, and expose the confidence field directly to users. Submission consultants can produce research briefs with evidence behind each fit recommendation. Curators can compare peer programs without manually tagging every title.

Confidence should affect how your application presents a result. A profile based on a large, well-populated roster can support a more specific explanation. If a festival has fewer than three roster entries, the endpoint still returns a profile, but marks it very_low with insufficient-data context instead of failing. Your interface can show the festival while making the limitation plain.

The automatic refresh behavior is useful for monitoring tools. When Festival API's roster changes, the programming profile is recomputed. The next request reflects the revised history and returns a current last_verified_at value.

Why runtime and production country are null

The response includes runtime_analysis and production_country_distribution, but both are currently null. Historical roster records do not carry runtime or production-country fields, so Festival API does not infer or invent them.

This is intentional. A null value tells your application that the metric is unavailable. Treat it as missing evidence, not as a zero, an empty distribution, or proof that the festival has no preference. If those fields become supported by the roster data later, clients can use the same response shape without a breaking change.

Call the endpoint with cURL, Python, or JavaScript

All direct API requests use a Bearer token. Replace YOUR_API_KEY with a key from your Festival API dashboard.

cURL

API_KEY="replace-with-your-key"
curl -H "Authorization: Bearer ${API_KEY}" \
  "https://festivalapi.com/v1/festivals/2629/programming-profile/"

Python

import requests

url = "https://festivalapi.com/v1/festivals/2629/programming-profile/"
response = requests.get(
    url,
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
profile = response.json()

print(profile["festival_name"])
print(profile["dominant_categories"])
print(profile["confidence"])

JavaScript

const response = await fetch(
  "https://festivalapi.com/v1/festivals/2629/programming-profile/",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);

if (!response.ok) {
  throw new Error(`Festival API returned ${response.status}`);
}

const profile = await response.json();
console.log(profile.festival_name, profile.dominant_categories);

RapidAPI users can request the same profile through GET /v1/rapidapi/festivals/{id}/programming-profile/ using the authentication headers supplied by RapidAPI.

Build festival-fit research on observed programming

Programming history cannot guarantee a selection, but it can make festival research more defensible. Instead of treating every category label as equal, you can see which types of films recur, how much history supports the result, where the data is sparse, and when the profile was last verified.

Create a Festival API account and get an API key, then read the Programming Profiles documentation for the endpoint details and response format. Each profile request costs 5 credits.