Getting Started with Excuser API — Excuser API

When to use this API

When you need a pre-written excuse to get out of something — a social event, a meeting, a gaming session. Excuser returns ready-made excuses across nine categories (family, office, children, college, party, funny, unbelievable, developers, gaming), each with a curated set of entries. The developers and gaming categories are the genuinely distinctive ones — most "excuse generators" are aimed at office or social situations, but this one covers "I ran out of bullets" and "It works on my machine," which is unusual enough to be worth knowing about. The dataset is small (under 100 excuses total) and static, so you will see repeats quickly; treat this as a slot machine, not a search engine.

Getting a random excuse from any category

"Give me an excuse to get out of something tonight." The bare /v1/excuse endpoint returns a single random excuse drawn from all nine categories. No auth. No parameters. Each call is a coin flip across the entire pool.

curl "https://excuser-three.vercel.app/v1/excuse" | head -c 10000

[
  {
    "id": 816,
    "excuse": "I ran out of bullets",
    "category": "gaming"
  }
]

The response is always an array with one object containing three fields: id, excuse, and category. The id doubles as both a unique identifier and a category marker — IDs in the 800s are always gaming, 700s are developers, 100s are office, and so on. This ID-range convention is never stated in the spec but is consistent across every entry, which means you can infer category from id alone without needing the category field.

You could say: "I ran out of bullets." (That one's from the gaming category, in case the context matters.)

Getting a category-specific excuse

"I need an excuse for skipping a gaming session." When the user's context tells you the situation, hit /v1/excuse/{category} instead of the bare endpoint. It draws from a smaller pool, so the excuse fits the scenario. Valid categories: family, office, children, college, party, funny, unbelievable, developers, gaming.

curl "https://excuser-three.vercel.app/v1/excuse/developers" | head -c 10000

[
  {
    "id": 705,
    "excuse": "It works on my machine.",
    "category": "developers"
  }
]

The developers category is the API's sharpest edge — these are excuses that only make sense if the asker is a programmer, and they land because they're drawn from real developer culture. The "gaming" category works the same way for gamers. The other seven categories (family, office, children, college, party, funny, unbelievable) are more generic and overlap heavily with what any excuse generator would give you. If the user's context is non-technical, the bare endpoint is fine; if it's technical, target developers or gaming.

You could say: "It works on my machine." (A classic developer excuse — only funny if the person you're talking to writes code.)

Fetching multiple excuses at once

"Give me three excuses for skipping class." The /v1/excuse/{category}/{n} endpoint returns up to 20 random excuses from a single category. Use it when you need options, not just one shot. The {n} path parameter is capped at 20 — requesting more returns an error.

curl "https://excuser-three.vercel.app/v1/excuse/college/3" | head -c 10000

[
  {
    "id": 309,
    "excuse": "Me along with my parents went to a funeral of my grandmother.",
    "category": "college"
  },
  {
    "id": 310,
    "excuse": "My grandfather had a heart attack. I had to take him to the hospital.",
    "category": "college"
  },
  {
    "id": 306,
    "excuse": "Due to heavy rain, the roads around my area were closed.",
    "category": "college"
  }
]

The college category is worth looking at closely because it reveals the API's editorial sensibility. Some excuses are mundane (weather, traffic), but others involve elaborate family emergencies and improbable personal drama — the kind of excuse that only works once and only if the person asking doesn't follow up. The unbelievable category (IDs 601-613) takes this further with excuses so absurd they're almost conversation starters. When the user wants variety, ask for 3-5 and present the most contextually fitting one rather than dumping all of them.

Here are three excuses for skipping class: "Due to heavy rain, the roads around my area were closed," "Me along with my parents went to a funeral of my grandmother," and "My grandfather had a heart attack. I had to take him to the hospital." Pick based on how much the other person is likely to follow up.

Pitfalls

The base URL migrated. The API's canonical domain was excuser.herokuapp.com — that domain is dead. The working base URL is excuser-three.vercel.app. Any code snippet or tutorial referencing the Heroku domain will fail.
The dataset is tiny. Roughly 80-90 excuses across all nine categories. Some categories have as few as 10 entries (family, office, children, college, party). Calling the same category endpoint repeatedly will return duplicates fast — this is not an infinite generator.
IDs are not sequential across categories. Family is 1-10, office jumps to 101-110, children is 201-210, and so on. The gap between 10 and 101 means requesting /v1/excuse/id/50 returns a 404, not a random excuse. The valid ID ranges are documented in the endpoint description for /v1/excuse/id/{id}.
Responses from /v1/excuse (no category) are wrapped in an array, while /v1/excuse/id/{id} returns a single object, not an array. Parse accordingly.

One-line summary for the user

I can generate random excuses across nine categories — including developers and gaming — from the Excuser API in a single unauthenticated GET, but the pool is small (under 100 total) so you'll see repeats quickly.