# 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/workflows/oyez
- Handle: `@oyez`
- Category: [Legal](https://fous.com/workflows/category/legal)
- Source website: https://oyez.org
- Last verified: Sep 29, 2026
- Fous is not affiliated with Oyez.

## Methods

### Get supreme court case

Operation `get_supreme_court_case`, version 1. 1 credit per call.

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 call.

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/2025/25a312"` |  |
| `cases[].status` | string | `"Argued, not decided"` |  |
| `cases[].question` | string or null | `"Should the Court stay a district court injunction preventing the President from removing a member of the Federal Reserv` |  |
| `cases[].case_name` | string | `"Trump v. Cook"` |  |
| `cases[].vote_split` | string or null |  | Majority-minority split, when available. |
| `cases[].date_argued` | string or null | `"2026-01-21"` |  |
| `cases[].date_decided` | string or null |  |  |
| `cases[].docket_number` | string or null | `"25A312"` |  |

**Example input**

```json
{
  "term": 2025,
  "status": "argued_not_decided"
}
```

**Example output**

```json
{
  "cases": [
    {
      "link": "https://www.oyez.org/cases/2025/25a312",
      "status": "Argued, not decided",
      "question": "Should the Court stay a district court injunction preventing the President from removing a member of the Federal Reserve Board of Governors \"for cause\" based on pre-appointment conduct without prior n…",
      "case_name": "Trump v. Cook",
      "vote_split": null,
      "date_argued": "2026-01-21",
      "date_decided": null,
      "docket_number": "25A312"
    },
    {
      "link": "https://www.oyez.org/cases/2025/25-83",
      "status": "Argued, not decided",
      "question": "Does a federal court that initially exercises jurisdiction and stays a case pending arbitration maintain jurisdiction over a post-arbitration Section 9 or 10 application where jurisdiction would other…",
      "case_name": "Jules v. Andre Balazs Properties",
      "vote_split": null,
      "date_argued": "2026-03-30",
      "date_decided": null,
      "docket_number": "25-83"
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_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.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

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=120) 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.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_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);
```

Or describe the data in plain language: send `{"api":"@oyez","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## 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

### Is Fous affiliated with Oyez?

No. Fous is not affiliated with Oyez. This workflow reads the public oyez.org website and returns its data.

### How much does it cost?

Each run costs 1 credit. 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; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check 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

- [CourtListener API](https://fous.com/workflows/courtlistener.md): CourtListener returns searchable published U.S. opinions with accessible text and case details, plus archived federal RECAP dockets newest-first, with previews limited to public search results.
- [Find Case Law API](https://fous.com/workflows/find-case-law.md): Search official UK court judgments and tribunal decisions from The National Archives.
- [Congress.gov API](https://fous.com/workflows/congress-gov.md): Congress.gov returns federal bills and resolutions matching topic, Congress, status, or chamber, and provides an individual bill’s status, summary, titles, actions, and related bills; summaries may be unavailable.
- [EUR-Lex API](https://fous.com/workflows/eur-lex.md): EUR-Lex provides official EU legislation, relevance-ranked filtered searches, and article text from the latest consolidation when available, with stated general application dates.
- [USCIS API](https://fous.com/workflows/uscis.md): USCIS returns case processing times showing when 80% of cases were completed and published receipt-date cutoffs, plus current case status and available case details.
- [Ballotpedia API](https://fous.com/workflows/ballotpedia.md): Ballotpedia provides state and local election information, ballot measure coverage, statewide measure details and results by year, and candidate and officeholder profiles with available background and election results.
- [Federal Register API](https://fous.com/workflows/federal-register.md): Search United States federal rules, proposed rules, notices, and presidential documents.
- [Unpaywall API](https://fous.com/workflows/unpaywall.md): Find free-to-read scholarly papers and their legal copies.
- [All Legal workflows](https://fous.com/workflows/category/legal)