# Oyez API

> Oyez provides Supreme Court case summaries, decisions, and votes as a workflow and API.

Oyez, also called The Oyez Project, returns case summaries, decisions, and votes from a case name or Oyez case link. List term cases returns cases for a Supreme Court term year, optionally filtered by status.

- Page: https://fous.com/tools/oyez
- Handle: `@oyez`
- Category: [Legal](https://fous.com/tools/category/legal)
- Source website: https://oyez.org
- Last verified: Sep 29, 2026

## Methods

### Get supreme court case

Operation `get_supreme_court_case`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get an Oyez Supreme Court case summary, decision and votes from its name or case link. Some cases lack structured voting records, citations or argument audio.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `case` | string | yes | `"Brown v. Board of Education"` | Case name or Oyez case link, for example Brown v. Board of Education or https://www.oyez.org/cases/2021/19-1392. |
| `term` | integer | no | `1954` | Supreme Court term year to choose between similar names, for example 1953. Omit to choose the closest matching case. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "case"
  ],
  "properties": {
    "case": {
      "type": "string",
      "description": "Case name or Oyez case link, for example Brown v. Board of Education or https://www.oyez.org/cases/2021/19-1392.",
      "examples": [
        "Brown v. Board of Education",
        "Dobbs v. Jackson",
        "https://www.oyez.org/cases/2021/19-1392"
      ]
    },
    "term": {
      "type": "integer",
      "description": "Supreme Court term year to choose between similar names, for example 1953. Omit to choose the closest matching case.",
      "examples": [
        1954
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "case": "Brown v. Board of Education"
    },
    {
      "case": "Dobbs v. Jackson"
    },
    {
      "case": "https://www.oyez.org/cases/2021/19-1392"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `term` | string or null | `"1953"` |  |
| `citation` | string or null | `"347 U.S. 483 (1954)"` |  |
| `decision` | string or null | `"for Brown et al."` |  |
| `question` | string or null | `"Does the segregation of public education based solely on race violate the Equal Protection Clause of the Fourteenth Ame` |  |
| `case_name` | string | `"Brown v. Board of Education of Topeka (1)"` |  |
| `oyez_link` | string | `"https://www.oyez.org/cases/1940-1955/347us483"` |  |
| `conclusion` | string or null |  |  |
| `vote_split` | string or null | `"9-0"` |  |
| `date_argued` | string or null | `"1952-12-09"` |  |
| `lower_court` | string or null | `"Federal district court"` |  |
| `date_decided` | string or null | `"1954-05-17"` |  |
| `docket_number` | string or null | `"1"` |  |
| `justice_votes` | array |  |  |
| `justice_votes[].name` | string | `"Earl Warren"` |  |
| `justice_votes[].vote` | string | `"majority"` |  |
| `facts_of_the_case` | string or null | `"After its decision in Brown v. Board of Education of Topeka ( Brown I ), which declared racial discrimination in public` |  |
| `argument_audio_links` | array |  |  |
| `majority_opinion_author` | string or null | `"Earl Warren"` |  |

**Example input**

```json
{
  "case": "Brown v. Board of Education"
}
```

**Example output**

```json
{
  "term": "1953",
  "citation": "347 U.S. 483 (1954)",
  "decision": "for Brown et al.",
  "question": "Does the segregation of public education based solely on race violate the Equal Protection Clause of the Fourteenth Amendment?",
  "case_name": "Brown v. Board of Education of Topeka (1)",
  "oyez_link": "https://www.oyez.org/cases/1940-1955/347us483",
  "conclusion": "Separate but equal educational facilities for racial minorities is inherently unequal, violating the Equal Protection Clause of the Fourteenth Amendment. Chief Justice Earl Warren delivered the opinio…",
  "vote_split": "9-0",
  "date_argued": "1952-12-09",
  "lower_court": "Federal district court",
  "date_decided": "1954-05-17",
  "docket_number": "1",
  "justice_votes": [
    {
      "name": "Earl Warren",
      "vote": "majority"
    },
    {
      "name": "Hugo L. Black",
      "vote": "majority"
    },
    {
      "name": "Stanley Reed",
      "vote": "majority"
    }
  ],
  "facts_of_the_case": "This case was the consolidation of cases arising in Kansas, South Carolina, Virginia, Delaware, and Washington D.C. relating to the segregation of public schools on the basis of race. In each of the c…",
  "argument_audio_links": [],
  "majority_opinion_author": "Earl Warren"
}
```

### List term cases

Operation `list_term_cases`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

List Oyez Supreme Court cases for a term, sorted by argument date then name. Decision dates and vote splits are blank where Oyez does not provide them.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `term` | integer | yes | `2023` | Year the Supreme Court term began, for example 2023 for the October 2023 term. |
| `status` | string | no | `"argued_not_decided"` | Choose all, decided, argued_not_decided, or not_yet_argued; for example, decided. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "term"
  ],
  "properties": {
    "term": {
      "type": "integer",
      "examples": [
        2023
      ],
      "description": "Year the Supreme Court term began, for example 2023 for the October 2023 term."
    },
    "status": {
      "enum": [
        "all",
        "decided",
        "argued_not_decided",
        "not_yet_argued"
      ],
      "type": "string",
      "default": "all",
      "description": "Choose all, decided, argued_not_decided, or not_yet_argued; for example, decided.",
      "examples": [
        "argued_not_decided",
        "all",
        "not_yet_argued"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "term": 2023
    },
    {
      "term": 2025,
      "status": "argued_not_decided"
    },
    {
      "term": 1800,
      "status": "all"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `cases` | array |  | Supreme Court cases for the selected term and status. |
| `cases[].link` | string | `"https://www.oyez.org/cases/2023/22-340"` |  |
| `cases[].status` | string | `"Decided"` |  |
| `cases[].question` | string or null | `"Must a defendant show he does not meet any of the criteria listed in 18 U.S.C. § 3553(f) to qualify for a sentence lowe` |  |
| `cases[].case_name` | string | `"Pulsifer v. United States"` |  |
| `cases[].vote_split` | string or null | `"6-3"` | Majority-minority split, when available. |
| `cases[].date_argued` | string or null | `"2023-10-02"` |  |
| `cases[].date_decided` | string or null | `"2024-03-15"` |  |
| `cases[].docket_number` | string or null | `"22-340"` |  |

**Example input**

```json
{
  "term": 2023
}
```

**Example output**

```json
{
  "cases": [
    {
      "link": "https://www.oyez.org/cases/2023/22-340",
      "status": "Decided",
      "question": "Must a defendant show he does not meet any of the criteria listed in 18 U.S.C. § 3553(f) to qualify for a sentence lower than the statutory minimum?",
      "case_name": "Pulsifer v. United States",
      "vote_split": "6-3",
      "date_argued": "2023-10-02",
      "date_decided": "2024-03-15",
      "docket_number": "22-340"
    },
    {
      "link": "https://www.oyez.org/cases/2023/22-448",
      "status": "Decided",
      "question": "Does the funding scheme for the Consumer Financial Protection Bureau, which receives funding directly from the Federal Reserve, violate the Appropriations Clause of the Constitution?",
      "case_name": "Consumer Financial Protection Bureau v. Community Financial Services Association of America",
      "vote_split": "7-2",
      "date_argued": "2023-10-03",
      "date_decided": "2024-05-16",
      "docket_number": "22-448"
    },
    {
      "link": "https://www.oyez.org/cases/2023/22-429",
      "status": "Decided",
      "question": "Does an ADA “tester” have Article III standing to challenge a hotel’s failure to provide disability accessibility information on its website, even if she has no plans to visit the hotel?",
      "case_name": "Acheson Hotels, LLC v. Laufer",
      "vote_split": "9-0",
      "date_argued": "2023-10-04",
      "date_decided": "2023-12-05",
      "docket_number": "22-429"
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@oyez",
  "visibility": "public",
  "operation": "get_supreme_court_case",
  "version": 1,
  "input": {
    "case": "Brown v. Board of Education"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@oyez\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_supreme_court_case\",\n  \"version\": 1,\n  \"input\": {\n    \"case\": \"Brown v. Board of Education\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@oyez",
  "visibility": "public",
  "operation": "get_supreme_court_case",
  "version": 1,
  "input": {
    "case": "Brown v. Board of Education"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/oyez`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_supreme_court_case`: Get supreme court case. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `list_term_cases`: List term cases. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-oyez https://api.fous.com/mcp/tools/oyez --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Review Supreme Court case summaries and decisions
- Compare justice votes across cases
- Find cases argued during a Supreme Court term
- Track cases by decision status
- Identify cases by docket number or citation

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Oyez tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Oyez account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from oyez.org when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What did the Supreme Court decide in a case?

Get supreme court case returns the decision and case summary from a case name or Oyez case link.

### How did the justices vote in a case?

Get supreme court case returns justice votes when structured voting records are available.

### Which cases were argued during a term?

List term cases returns cases for a term year, with argument dates and optional status filtering.

## Related

- [All Legal tools](https://fous.com/tools/category/legal)