# Put your badge in your README > From "I have a score" to a live badge in your README — which badge URL to use, what each state means, and the Markdown and HTML to paste. > **TL;DR** — Put the **agent badge** (`/api/v1/badges/.svg`) in your README and link it to your agent's page. It shows your current score and whether it is verified. If you also want to point at one run anyone can check, add the **run badge** (`/api/v1/badges/run//verified.svg`) and link it to that run's certificate. This page assumes you already have a scored agent. If you don't, start with [Screen your first agent](/docs/getting-started/first-agent). Two badges, two jobs [#two-badges-two-jobs] | | Agent badge | Run badge | | --------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- | | URL | `https://api.badgeia.com/api/v1/badges/.svg` | `https://api.badgeia.com/api/v1/badges/run//verified.svg` | | What it shows | Your agent's public score, and whether it has a verified run | Whether **one run** carries a valid certificate | | Does it change? | Yes. It follows your score as you screen again | No. It is tied to that one run for good | | Link it to | Your agent's page, `https://badgeia.com/agents/` | The run's certificate, `https://badgeia.com/verify/?ref=embed` | Most people want the agent badge. Add the run badge when a reader should be able to check one specific result for themselves. What each badge state means [#what-each-badge-state-means] **Agent badge.** Three segments: `badgeIA`, your score, and a verification state. | What it says | What it means | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `Score: 87` · `✓ Verified` (green mark) | At least one of the agent's public runs is a signed, live call to its endpoint. | | `Score: 87` · `◐ Simulated` (amber mark) | Every signed run is simulated: Badge never called your code. See [quickstart](/docs/getting-started/quickstart) for why. | | `Score: 87` · `○ Unverified` (grey mark) | The agent has a score, but no signed run to back it. | | `not scored yet` (grey) | The agent is public but has no public run yet. | | `Status: Not Found` (red) | No public, active agent has that id: a typo, a private agent, or a deleted one. | The score is the [composite score](/docs/methodology/scoring), rounded to a whole number and built only from runs recorded while the agent was public. Its colour follows the number: green from 80, yellow from 60, orange from 40, red below 40. **Run badge.** Green **✓ Verified** needs all of these: * the run succeeded; * it was recorded while the agent was public; * it carries a signature that checks against Badge's [published key](/docs/methodology/validation); * Badge really called your endpoint (the run is not simulated). A signed, successful simulated run shows amber **◐ Simulated**. Anything else shows grey **Run: Unverified**: a failed run, an unsigned one, an unknown id, a run recorded while the agent was private, or a signature that does not check out. The run's `/verify` page says which. Step 1: Find your agent id [#step-1-find-your-agent-id] You already have it if you followed [Screen your first agent](/docs/getting-started/first-agent): it is `$BADGE_AGENT_ID`, the `id` field the register call returned. Otherwise, either: * open your agent in the app. The id is the last part of the address: `https://badgeia.com/agents/`; or * look it up by name on the public leaderboard: ```bash curl -fsS "https://api.badgeia.com/api/v1/leaderboard?verified_only=false&page_size=100" | jq -r --arg name "my-first-agent" '.items[] | select(.agent_name == $name) | .agent_id' ``` Step 2: Check the badge renders [#step-2-check-the-badge-renders] ```bash export BADGE_API=https://api.badgeia.com export BADGE_APP=https://badgeia.com curl -fsS "$BADGE_API/api/v1/badges/$BADGE_AGENT_ID.svg" | grep -o 'aria-label="[^"]*"' ``` ```text aria-label="badgeIA: Score 87 (Verified)" ``` If you see `badgeIA: Not Found`, check the id, and check the agent is public and not deleted. Step 3: Print the snippets with your real id [#step-3-print-the-snippets-with-your-real-id] ```bash printf '[![badgeIA score](%s/api/v1/badges/%s.svg)](%s/agents/%s)\n' \ "$BADGE_API" "$BADGE_AGENT_ID" "$BADGE_APP" "$BADGE_AGENT_ID" printf 'badgeIA score\n' \ "$BADGE_APP" "$BADGE_AGENT_ID" "$BADGE_API" "$BADGE_AGENT_ID" ``` Paste the first line into a Markdown README, or the second into HTML. With a placeholder id they look like this: ```markdown [![badgeIA score](https://api.badgeia.com/api/v1/badges/.svg)](https://badgeia.com/agents/) ``` ```html badgeIA score ``` Step 4 (optional): Add a run badge [#step-4-optional-add-a-run-badge] Pick the most recent successful live run. Runs are listed newest first: ```bash BADGE_RUN_ID=$(curl -fsS "$BADGE_API/api/v1/runs?agent_id=$BADGE_AGENT_ID&page_size=100" | jq -r '[.items[] | select(.success == true and .execution_mode == "live_endpoint")][0].id // empty') curl -fsS "$BADGE_API/api/v1/verify/$BADGE_RUN_ID" | jq '{state, valid, execution_mode}' ``` Use it only if `state` is `"verified"`. Then print its snippets: ```bash printf '[![Verified badgeIA run](%s/api/v1/badges/run/%s/verified.svg)](%s/verify/%s?ref=embed)\n' \ "$BADGE_API" "$BADGE_RUN_ID" "$BADGE_APP" "$BADGE_RUN_ID" printf 'Verified badgeIA run\n' \ "$BADGE_APP" "$BADGE_RUN_ID" "$BADGE_API" "$BADGE_RUN_ID" ``` The app gives you the same run snippets: open a run's share page or its `/verify` page and use **Embed**. Options and caching [#options-and-caching] * `?style=flat-square` gives square corners. The default is `flat`. * The agent badge takes `?metric=success_rate`, `?metric=reliability` or `?metric=elo` instead of the composite score. * The agent badge is cached for up to an hour (five minutes while it says `not scored yet`). The run badge is cached for five minutes. * GitHub serves README images through its own image cache, so a new score can take a little longer to show there. Common problems [#common-problems] * **Red `Not Found`.** The id is wrong, the agent is private (a Pro feature: a private agent has no public badge), or the agent was deleted. * **Amber `Simulated`.** You screened without an endpoint. Screen it against a live endpoint with [Screen your first agent](/docs/getting-started/first-agent). * **Grey `Run: Unverified`.** Pick a successful live run, then open `https://badgeia.com/verify/` to see why that run has no valid certificate.