VExUS C (venous excess ultrasound)

VExUS C

Apply Beaubien-Souligny 2020 VExUS prototype C and return vexus_grade 0-3 from a caller-assigned IVC dilatation flag and hepatic, portal, and intra-renal venous Doppler grades.

LIVE $0.005 USDC GET /api/calc/vexus

Markdown: /docs/vexus.md · Canonical: https://magentlab.com/docs/vexus

Not a medical device. Not a diagnosis, dose, or listing recommendation.

What it computes

Apply Beaubien-Souligny 2020 VExUS prototype C and return vexus_grade 0-3 from a caller-assigned IVC dilatation flag and hepatic, portal, and intra-renal venous Doppler grades.

When to use

When an agent already has a caller-assigned IVC dilatation flag (maximal diameter ≥2 cm) and hepatic, portal, and intra-renal venous Doppler grades (normal, mild, or severe) and needs the published VExUS C grade. magent does not perform ultrasound.

When not to use

Not a medical device.
VExUS C only. Does not implement prototypes A, B, D, or E.
The caller assigns ivc_dilated and the three Doppler grades. magent does not perform ultrasound or measure IVC.
Not an AKI diagnosis. Does not report AKI probability percents.
Not a fluid-order.

Formula

VExUS C grade 0 if ivc_dilated is false (regardless of Doppler); else 1 if zero of hepatic/portal/renal are severe; 2 if exactly one is severe; 3 if two or more are severe (Beaubien-Souligny 2020 prototype C). Hepatic: normal (triphasic S>D toward liver), mild (S<D toward liver), severe (S reversed toward heart). Portal: mild pulsatility 30 to <50%, severe ≥50%. Renal: mild discontinuous S and D, severe only D. IVC dilated iff maximal diameter ≥2 cm as assigned. Not prototypes A, B, D, E

Citation

Title: Quantifying systemic congestion with Point-Of-Care ultrasound: development of the venous excess ultrasound grading system
Authors: Beaubien-Souligny W, Rola P, Haycock K, Bouchard J, Lamarche Y, Spiegel R, Denault AY
Source: Ultrasound J. 2020;12(1):16
DOI: 10.1186/s13089-020-00163-w

Worked example

IVC not dilated, all Doppler normal (grade 0)

Given: hepatic=normalivc_dilated=falseportal=normalrenal=normal

ivc_dilated is false (maximal IVC diameter not ≥2 cm as assigned)
hepatic, portal, and renal are normal
Grade is 0 regardless of Doppler; severe_doppler_count is 0

Dilated IVC, all Doppler normal (grade 1)

Given: hepatic=normalivc_dilated=trueportal=normalrenal=normal

ivc_dilated is true (maximal IVC diameter ≥2 cm as assigned)
hepatic is normal (triphasic S > D toward the liver)
portal is normal (non-pulsatile portal flow)
renal is normal (continuous intra-renal venous flow)
Zero severe Doppler patterns; vexus_grade is 1

Dilated IVC, one severe Doppler (grade 2)

Given: hepatic=severeivc_dilated=trueportal=normalrenal=normal

ivc_dilated is true
hepatic is severe (S reversed toward the heart)
portal and renal are not severe
Exactly one severe Doppler pattern; vexus_grade is 2

Dilated IVC, three severe Doppler patterns (grade 3)

Given: hepatic=severeivc_dilated=trueportal=severerenal=severe

ivc_dilated is true
hepatic is severe (systolic reversal)
portal is severe (pulsatility ≥50%)
renal is severe (only a diastolic phase)
Two or more severe Doppler patterns with a dilated IVC; vexus_grade is 3

Also searched as

VExUS C
venous excess ultrasound
VExUS grading system
Beaubien-Souligny 2020
hepatic portal renal Doppler
IVC dilatation VExUS
venous congestion ultrasound
VExUS grade 0-3

Try

Opens the live endpoint. Unpaid browser requests show the paywall; agents should send Accept: application/json.

/api/calc/vexus?ivc_dilated=false&hepatic=normal&portal=normal&renal=normal

Full URL: https://api.magentlab.com/api/calc/vexus?ivc_dilated=false&hepatic=normal&portal=normal&renal=normal

Call

Expect HTTP 402 until you retry with PAYMENT-SIGNATURE. Incomplete query params return HTTP 400 before any quote or charge.

curl -i -H "Accept: application/json" "https://api.magentlab.com/api/calc/vexus?ivc_dilated=false&hepatic=normal&portal=normal&renal=normal"

Parameters

Name	Type	Required	Description
`ivc_dilated`	boolean	required	Whether the IVC is dilated as assigned by the caller. Dilated iff maximal IVC diameter ≥2 cm (Beaubien-Souligny 2020). true or false. Grade 0 whenever this is false, regardless of Doppler. magent does not measure IVC.
`hepatic`	string	required · normal, mild, severe	Hepatic-vein Doppler grade as assigned by the caller (Beaubien-Souligny 2020 Figure 1): normal (not mild and not severe; triphasic S > D toward the liver); mild (S component lower in magnitude than D but still toward the liver); severe (S component reversed, toward the heart). magent does not perform ultrasound.
`portal`	string	required · normal, mild, severe	Portal-vein Doppler grade as assigned by the caller (Beaubien-Souligny 2020 Figure 1 caption): normal (pulsatility fraction not in the mild or severe bands); mild (velocity variation 30 to <50%); severe (variation ≥50%). magent does not perform ultrasound.
`renal`	string	required · normal, mild, severe	Intra-renal venous Doppler grade as assigned by the caller (Beaubien-Souligny 2020 Figure 1): normal (continuous flow); mild (discontinuous with a systolic and a diastolic phase); severe (discontinuous with only a diastolic phase during the cardiac cycle). magent does not perform ultrasound.

Bulk (POST)

POST the same path with a JSON items array. The first item is the GET unit; each additional item is $0.002. Invalid items return HTTP 400 before settlement.

POST /api/calc/vexus Max 25 unit_amount + extra_item_amount * (n - 1) extra $0.002 PREVIEW

1 to 25 items. Each item uses the same keys as the GET query parameters.
POST of 1 item costs the same as GET. Lists longer than 25: chunk into multiple POSTs. Extra items still execute; do not pad dummy rows.
The first invalid item fails the whole request (index in the 400 JSON). You are not charged.
HTTP 200 is {count, path, items}. Each items[i] is the GET 200 body for that row.
Catalog misses (empty matches, found=false) stay paid 200s inside that slot.
x402 resource URL is this path plus n and body_sha256. Browsers that prefer text/html get the same paywall as GET; Pay retries POST with the same items.

Example request (fixture)

{
  "items": [
    {
      "hepatic": "normal",
      "ivc_dilated": "false",
      "portal": "normal",
      "renal": "normal"
    },
    {
      "hepatic": "normal",
      "ivc_dilated": "false",
      "portal": "normal",
      "renal": "normal"
    }
  ]
}

Open bulk paywall →

Opens a two-item fixture on the API host. Unpaid browsers get the same MetaMask paywall as GET; Pay retries POST with those items.

Example 200 (fixture)

{
  "count": 2,
  "path": "/api/calc/vexus",
  "items": [
    {
      "components": [
        {
          "factor": "ivc_dilated",
          "met": false
        },
        {
          "value": "normal",
          "factor": "hepatic_severe",
          "met": false
        },
        {
          "value": "normal",
          "factor": "portal_severe",
          "met": false
        },
        {
          "value": "normal",
          "factor": "renal_severe",
          "met": false
        },
        {
          "factor": "grade_0",
          "met": true
        },
        {
          "factor": "grade_1",
          "met": false
        },
        {
          "factor": "grade_2",
          "met": false
        },
        {
          "factor": "grade_3",
          "met": false
        }
      ],
      "portal": "normal",
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "citation": {
        "authors": "Beaubien-Souligny W, Rola P, Haycock K, Bouchard J, Lamarche Y, Spiegel R, Denault AY",
        "doi": "10.1186/s13089-020-00163-w",
        "id": "beaubien-souligny-2020",
        "pmid": "32270297",
        "source": "Ultrasound J. 2020;12(1):16",
        "title": "Quantifying systemic congestion with Point-Of-Care ultrasound: development of the venous excess ultrasound grading system"
      },
      "formula": "vexus",
      "formula_expression": "VExUS C grade 0 if ivc_dilated is false (regardless of Doppler); else 1 if zero of hepatic/portal/renal are severe; 2 if exactly one is severe; 3 if two or more are severe (Beaubien-Souligny 2020 prototype C). Hepatic: normal (triphasic S>D toward liver), mild (S<D toward liver), severe (S reversed toward heart). Portal: mild pulsatility 30 to <50%, severe ≥50%. Renal: mild discontinuous S and D, severe only D. IVC dilated iff maximal diameter ≥2 cm as assigned. Not prototypes A, B, D, E",
      "hepatic": "normal",
      "ivc_dilated": false,
      "renal": "normal",
      "severe_doppler_count": 0,
      "vexus_grade": 0
    },
    {
      "components": [
        {
          "factor": "ivc_dilated",
          "met": false
        },
        {
          "value": "normal",
          "factor": "hepatic_severe",
          "met": false
        },
        {
          "value": "normal",
          "factor": "portal_severe",
          "met": false
        },
        {
          "value": "normal",
          "factor": "renal_severe",
          "met": false
        },
        {
          "factor": "grade_0",
          "met": true
        },
        {
          "factor": "grade_1",
          "met": false
        },
        {
          "factor": "grade_2",
          "met": false
        },
        {
          "factor": "grade_3",
          "met": false
        }
      ],
      "portal": "normal",
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "citation": {
        "authors": "Beaubien-Souligny W, Rola P, Haycock K, Bouchard J, Lamarche Y, Spiegel R, Denault AY",
        "doi": "10.1186/s13089-020-00163-w",
        "id": "beaubien-souligny-2020",
        "pmid": "32270297",
        "source": "Ultrasound J. 2020;12(1):16",
        "title": "Quantifying systemic congestion with Point-Of-Care ultrasound: development of the venous excess ultrasound grading system"
      },
      "formula": "vexus",
      "formula_expression": "VExUS C grade 0 if ivc_dilated is false (regardless of Doppler); else 1 if zero of hepatic/portal/renal are severe; 2 if exactly one is severe; 3 if two or more are severe (Beaubien-Souligny 2020 prototype C). Hepatic: normal (triphasic S>D toward liver), mild (S<D toward liver), severe (S reversed toward heart). Portal: mild pulsatility 30 to <50%, severe ≥50%. Renal: mild discontinuous S and D, severe only D. IVC dilated iff maximal diameter ≥2 cm as assigned. Not prototypes A, B, D, E",
      "hepatic": "normal",
      "ivc_dilated": false,
      "renal": "normal",
      "severe_doppler_count": 0,
      "vexus_grade": 0
    }
  ]
}

Response

Field	Type	Description
`formula`	string	vexus
`formula_expression`	string	Published Beaubien-Souligny 2020 VExUS C grade rule
`vexus_grade`	integer	VExUS C grade 0-3. 0 if the IVC is not dilated; 1 if dilated with zero severe Doppler patterns; 2 if dilated with exactly one severe; 3 if dilated with two or more severe. Not an AKI diagnosis.
`severe_doppler_count`	integer	Count of hepatic, portal, and renal that are severe (0-3), independent of IVC dilatation
`ivc_dilated`	boolean	Echo of the caller-assigned IVC dilatation flag
`hepatic`	string	Echo of the caller-assigned hepatic-vein Doppler grade
`portal`	string	Echo of the caller-assigned portal-vein Doppler grade
`renal`	string	Echo of the caller-assigned intra-renal venous Doppler grade
`components`	array	Rows for ivc_dilated, hepatic_severe, portal_severe, renal_severe, and exclusive grades grade_0 through grade_3 with factor, met, and value where assigned
`citation`	object	Beaubien-Souligny 2020 Ultrasound J citation
`disclaimer`	string	Not-a-device notice

Example JSON

Machine form of the same example. Frozen fixture. Not a live lookup.

{
  "components": [
    {
      "factor": "ivc_dilated",
      "met": false
    },
    {
      "value": "normal",
      "factor": "hepatic_severe",
      "met": false
    },
    {
      "value": "normal",
      "factor": "portal_severe",
      "met": false
    },
    {
      "value": "normal",
      "factor": "renal_severe",
      "met": false
    },
    {
      "factor": "grade_0",
      "met": true
    },
    {
      "factor": "grade_1",
      "met": false
    },
    {
      "factor": "grade_2",
      "met": false
    },
    {
      "factor": "grade_3",
      "met": false
    }
  ],
  "portal": "normal",
  "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "citation": {
    "authors": "Beaubien-Souligny W, Rola P, Haycock K, Bouchard J, Lamarche Y, Spiegel R, Denault AY",
    "doi": "10.1186/s13089-020-00163-w",
    "id": "beaubien-souligny-2020",
    "pmid": "32270297",
    "source": "Ultrasound J. 2020;12(1):16",
    "title": "Quantifying systemic congestion with Point-Of-Care ultrasound: development of the venous excess ultrasound grading system"
  },
  "formula": "vexus",
  "formula_expression": "VExUS C grade 0 if ivc_dilated is false (regardless of Doppler); else 1 if zero of hepatic/portal/renal are severe; 2 if exactly one is severe; 3 if two or more are severe (Beaubien-Souligny 2020 prototype C). Hepatic: normal (triphasic S>D toward liver), mild (S<D toward liver), severe (S reversed toward heart). Portal: mild pulsatility 30 to <50%, severe ≥50%. Renal: mild discontinuous S and D, severe only D. IVC dilated iff maximal diameter ≥2 cm as assigned. Not prototypes A, B, D, E",
  "hepatic": "normal",
  "ivc_dilated": false,
  "renal": "normal",
  "severe_doppler_count": 0,
  "vexus_grade": 0
}

Client errors (HTTP 400)

Invalid params return 400 without charge. Shared HTTP 402 and 503 meanings: Payments.

HTTP	Code	When
400	`invalid_vexus`	hepatic, portal, and renal must each be normal, mild, or severe (Beaubien-Souligny 2020 VExUS C Doppler grades). Returned before settlement; you are not charged.
400	`invalid_flag`	boolean clinical flags must be true or false Returned before settlement; you are not charged.
400	`invalid_items`	POST body must be a JSON object with only an items array Returned before settlement; you are not charged.
400	`invalid_item_count`	items must be an array of 1 to 25 objects Returned before settlement; you are not charged.
400	`invalid_item`	each items entry must be a JSON object Returned before settlement; you are not charged.

Related tools

PAPi — Compute Korabathina 2012 pulmonary artery pulsatility index from PA systolic, PA diastolic, and right atrial pressure.
AKIN — Apply Mehta 2007 Table 2 AKIN staging and return stage 0-3 as the worse of the creatinine and urine-output limbs, with initiated renal replacement therapy mapping to stage 3.

Payment

Unpaid requests return HTTP 402 even if query parameters or POST items are missing or invalid, so CDP and agents can index the path. After a PAYMENT-SIGNATURE, invalid params return HTTP 400 JSON before settlement. magent does not charge. Fix the params, then request a new 402 quote for that complete URL. Catalog misses (empty matches, found=false) are valid paid 200s. Unpaid valid requests return HTTP 402 with a base64 PAYMENT-REQUIRED header. HTTP 503 is not a new quote: retry the same PAYMENT-SIGNATURE. Full handshake and shared payment errors: Payments. Stdio MCP: /docs/mcp.

Guarantees

HTTP 402 is unpaid, including a missing query. After PAYMENT-SIGNATURE, invalid parameters return HTTP 400 before settlement. You are not charged. HTTP 402 never includes the tool JSON.
exact: settlement finishes before the tool (paymentFlow upfront). batch-settlement: verify/deposit before the tool; chargedCumulativeAmount commits after HTTP 2xx. Uncertain or failed settlement fails closed (HTTP 503). Retry the same PAYMENT-SIGNATURE.
HTTP 402 is unpaid only. Do not sign a second authorization because of a 503.
Execution is timeout-bounded and concurrency-capped.
Calculator inputs are stored encrypted for allowlisted operators (Magent Console). They are not in public logs, SSH lookups, catalog, or rollups. Request logs store path without query.