Traverse the citation network

Citation graph traversal for US and Indian cases. Returns directed nodes and edges plus depth control, per-edge treatment hints, and a ranking of the most influential subsequent citers.

GET /api/v1/citations/cases/network

Traverse the citation network

cURL

curl --request GET \
  --url https://api.vaquill.ai/api/v1/citations/cases/network \
  --header 'Authorization: Bearer <token>'

200

us_depth1

{ "data": { "seed": { "clusterId": 108713, "caseName": "Roe v. Wade", "citation": "410 U.S. 113", "dateFiled": "1973-01-22", "citeCount": 5579, "absoluteUrl": "https://app.vaquill.ai/research/cases/108713" }, "depth": 1, "nodes": [ { "clusterId": 110075, "caseName": "Bell v. Wolfish", "citation": "441 U.S. 520", "dateFiled": "1979-05-14", "citeCount": 11402, "absoluteUrl": "https://app.vaquill.ai/research/cases/110075" }, { "clusterId": 109301, "caseName": "Warth v. Seldin", "citation": "422 U.S. 490", "dateFiled": "1975-06-25", "citeCount": 10851, "absoluteUrl": "https://app.vaquill.ai/research/cases/109301" } ], "edges": [ { "sourceClusterId": 110075, "targetClusterId": 108713, "direction": "cited", "depth": 1, "treatment": "positive", "snippet": "the court relied on the detainee's desire... fundamental liberty interests delineated in cases such as Roe" }, { "sourceClusterId": 109301, "targetClusterId": 108713, "direction": "cited", "depth": 1, "treatment": "neutral", "snippet": "See also Roe v. Wade for the principle." } ], "counts": { "cited": 10, "citingBy": 10, "total": 20, "positive": 1, "negative": 0, "neutral": 9, "unknown": 10 }, "topCitedBy": [ { "clusterId": 110075, "caseName": "Bell v. Wolfish", "citation": "441 U.S. 520", "dateFiled": "1979-05-14", "citeCount": 11402, "absoluteUrl": "https://app.vaquill.ai/research/cases/110075" } ] }, "meta": { "processingTimeMs": 9263.4, "creditsConsumed": 10, "creditsRemaining": 4990 } }

What this endpoint does

For US cases, citation data is sourced from CourtListener (a service of the Free Law Project - a US 501(c)(3) non-profit). CourtListener publishes the underlying opinions-cited pairs as structured data; Vaquill builds a directed-graph endpoint on top of that data with treatment classification and ranking:

• Both directions in one call. citing-by (subsequent citers) AND cites-to (authorities the seed relies on).
• Depth control. depth=1 returns immediate neighbors; depth=2 expands one more hop with bounded fan-out.
• Treatment hints. Each citing edge carries a treatment label derived from the citing context: positive (followed / affirmed / relied on), negative (overruled / distinguished / criticized), neutral, or unknown. We classify against the citation window in the citer’s opinion, not the whole document.
• topCitedBy ranking. The top 5 citing opinions ordered by their own forward-citation count. These are the cases that most carry the seed forward.

The graph endpoint includes a source_attribution block crediting CourtListener / Free Law Project; please surface that to your end users and consider donating if you build on this data.

Quick start (US)

curl "https://api.vaquill.ai/api/v1/citations/cases/network?clusterId=108713&countryCode=US&depth=1&limit=20" \
  -H "Authorization: Bearer vq_key_..."

clusterId=108713 is Roe v. Wade. Replace with any cluster ID, or pass citation=410 U.S. 113 and we’ll resolve it for you.

Cost

• Depth 1: 10 credits ($0.10).
• Depth 2: 25 credits ($0.25).

Authorizations

Authorization · string · header · required

API key issued from the Vaquill developer dashboard. Pass as Authorization: Bearer vq_key_...

Query Parameters

citation · string | null

Root citation. For India: SCR/INSC/SCC/AIR. For US: any Bluebook citation, or use clusterId instead.

Required string length: 3 - 200

clusterId · integer | null

US only. Vaquill case cluster ID. Faster than a citation string because it skips the resolution step.

Required range: x >= 1

direction · enum<string> · default: both

Traversal direction (India only).

Available options: outbound, inbound, both

depth · integer · default: 2

Max hops (1-3)

Required range: 1 <= x <= 3

limit · integer · default: 50

Max nodes (1-100)

Required range: 1 <= x <= 100

countryCode · string | null

ISO 3166-1 alpha-2 country code (e.g. IN for India). Reserved for future multi-jurisdiction support. Currently the dataset covers India only, so requests for other country codes will return empty results naturally from the database.

Response

200

application/json

Citation network graph. Response shape differs between US and India.

Top-level response for GET /citations/cases/network.

data · NetworkData · object · required

Data payload for the network endpoint.

Show child attributes

meta · CitationApiMeta · object · required

Metadata returned with every citation API response.

Show child attributes