Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Interfaces and Components

Examples, Flagging and API Names

Add clickable examples to a Gradio app, cache their outputs, collect user feedback with flagging, and name your API endpoints so clients can call them reliably.

A demo with an empty form invites questions: what should I type? Examples answer that. Flagging lets users report bad outputs. Stable API names let other programs call your app without breaking when you rearrange the page. These three features turn a toy into something other people can use. The Gradio code is read-only; stand-ins show the logic of caching and logging.

Examples

Python
import gradio as gr

def area(shape, size):
    return size * size if shape == "square" else round(3.14159 * size * size, 2)

demo = gr.Interface(
    fn=area,
    inputs=[gr.Radio(["square", "circle"], label="Shape"), gr.Number(label="Size")],
    outputs=gr.Number(label="Area"),
    examples=[
        ["square", 4],
        ["circle", 2],
        ["circle", 10],
    ],
)

Under the form, the page shows a table titled Examples with three rows. Clicking a row fills the inputs; the user then presses Submit. Each example is a list with one value per input component, in order.

You can also use files as examples (paths relative to your app), and examples_per_page controls paging. Helpful examples are short, cover different behaviours, and include a case that shows an interesting edge (for a classifier, one clear and one ambiguous input).

Caching example outputs

Python
demo = gr.Interface(fn=area, inputs=[...], outputs=..., examples=[...],
                    cache_examples=True)

With cache_examples=True, Gradio runs the function for every example at startup and stores the results. Clicking an example then shows the stored output instantly, without running the model. This is great for heavy models (a Space can show results without a GPU request) and for demos where the first impression matters. Costs: startup takes as long as all examples together, and the cached output is stale if you change the function without clearing the cache (delete the .gradio/cached_examples folder). cache_examples="lazy" computes each example the first time it is clicked.

Flagging

Flagging lets a user click a Flag button to save the current inputs and outputs for you to review, for example a wrong prediction.

Python
demo = gr.Interface(
    fn=area, inputs=[...], outputs=...,
    flagging_mode="manual",           # "never", "auto" or "manual"
    flagging_options=["Wrong answer", "Offensive", "Other"],
)

With "manual" the page shows a Flag button (or one button per option). "auto" flags every run without asking. By default the records go to a CSV file in a flagged/ folder next to your app; the columns are the component labels plus a timestamp and the chosen option. Because it is a plain file, the information is easy to load into pandas.

Flagged data contains whatever users typed or uploaded. Tell users that flagging stores their input, do not enable "auto" for private data, and keep the folder out of version control.

Custom destinations (a database, a Hugging Face dataset) are possible with a flagging callback class. The simplest pattern remains a CSV plus a weekly look.

API names and the Use via API page

Every event gets an API endpoint. Interface calls it /predict. In Blocks the default name comes from the function name, but you can set it directly:

Python
btn.click(fn=area, inputs=[shape, size], outputs=out, api_name="compute_area")

Then a client calls it by name:

Python
from gradio_client import Client

client = Client("http://127.0.0.1:7860/")
print(client.predict("circle", 2, api_name="/compute_area"))   # 12.57

Name endpoints explicitly in any app other people call; otherwise renaming a function silently renames the endpoint. Setting api_name=False hides an event from the API page, which is right for internal helper events such as "clear form". api_description adds a sentence to the generated docs. The Use via API link at the page bottom shows each endpoint with its parameters.

Stand-in 1: caching example outputs

Python Stand-in: precomputed example outputs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The clicks cost nothing because the answers were stored. If you edit area but keep the old cache, the examples show the old answers, so clear the cache when the function changes.

Stand-in 2: a flag log

Python Stand-in: write flagged rows to CSV

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The same file layout is what the real default flagging callback produces, so loading it with pandas to count problems is a realistic workflow.

Putting it together

flowchart LR
    U["User"] --> E["Click an example"]
    E --> R["Run function<br/>or show cached output"]
    R --> O["Output"]
    O --> F["Flag button"]
    F --> L["CSV log for review"]
    C["Other programs"] -->|"api_name"| R

Examples start the conversation, flags end it, and API names let machines join.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How is one example row structured?

    Examples fill the inputs, so each row needs a value for every input component.
  2. 2. What does cache_examples=True do?

    Clicking an example then shows the stored output instantly.
  3. 3. Why set api_name explicitly?

    A stable name is a contract with callers. Defaults can change with the code.
  4. 4. Where does default flagging store its data?

    The default callback appends rows to a CSV file; other destinations need a custom callback.

Summary

  • examples are lists with one value per input; they fill the form on click.
  • cache_examples precomputes outputs for instant results; clear it when the function changes.
  • Flagging records inputs and outputs for review; mind privacy.
  • Name endpoints with api_name and hide helpers with api_name=False.

Next: Dataframes and Plots