Which plan includes the CI cost gate?

Base, Growth and Business (and the 10-day trial).

What key does CI use?

A Cognocient proxy key, the same kind your app uses. Keep it in a CI secret. Proxy keys can run checks and set baselines but cannot manage team, billing, SSO or provider credentials.

Why did my check say No calls?

No calls were recorded with that run id in the last 30 days. Check that your app sends X-Cost-Run-Id with exactly the run id you pass to the check, and that its calls go through the Cognocient proxy.

What if the number of tests changes?

Total run cost will change too. Use compare per_call to compare the average cost per call instead.

How do I fail a CI build when a change makes AI calls more expensive?

Run your test suite through the Cognocient proxy with a run id, then call one endpoint that compares the run's cost with a baseline and fails the build on a regression. Base plan.

A prompt that doubles its context, a switch to a pricier model or a new retry loop usually shows up on the invoice weeks later. The cost gate catches it in the pull request.

How it works

Your tests run with LLM calls going through Cognocient, each sending X-Cost-Run-Id: ci-<commit>.
After the tests, CI calls POST /api/cost-gate/check with that run id.
Cognocient totals the run's calls and compares them with a named baseline (default main).
The response says whether the check passed, and why. The CI step fails if it did not.
On your main branch, update_baseline: true makes a passing run the new baseline.

1. Send the run id from your app

import os
from openai import OpenAI
 
run_id = os.environ.get("COGNOCIENT_RUN_ID")   # only set in CI
client = OpenAI(
    base_url="https://api.cognocient.com/v1",
    api_key=os.environ["COGNOCIENT_KEY"],
    default_headers={"X-Cost-Run-Id": run_id, "X-Cost-Environment": "ci"} if run_id else None,
)

Adding X-Cost-Environment: ci also lets you see and budget CI spend separately.

2. Add the gate to your workflow

- name: Tests (LLM calls go through Cognocient)
  env:
    COGNOCIENT_KEY: ${{ secrets.COGNOCIENT_KEY }}
    COGNOCIENT_RUN_ID: ci-${{ github.sha }}-${{ github.run_attempt }}
  run: pytest
 
- name: Cognocient cost gate
  env:
    COGNOCIENT_KEY: ${{ secrets.COGNOCIENT_KEY }}
  run: |
    RESULT=$(curl -sS -X POST https://api.cognocient.com/api/cost-gate/check \
      -H "Authorization: Bearer $COGNOCIENT_KEY" -H "Content-Type: application/json" \
      -d '{
        "run_id": "ci-${{ github.sha }}-${{ github.run_attempt }}",
        "baseline": "main",
        "max_increase_pct": 10,
        "update_baseline": ${{ github.ref == 'refs/heads/main' }},
        "commit_sha": "${{ github.sha }}",
        "branch": "${{ github.head_ref || github.ref_name }}"
      }')
    echo "$RESULT" | jq -r '.reasons[]? // empty'
    echo "$RESULT" | jq -e '.passed == true' > /dev/null || { echo "$RESULT"; exit 1; }

Any CI system works the same way: it is one HTTP call.

Options

Field	Default	Meaning
`run_id`	required	The run to check. Letters, digits and `. _ : / -`, up to 128 characters.
`baseline`	`main`	Name of the baseline to compare with.
`max_increase_pct`	`10`	Fail if cost rises by more than this percentage.
`max_cost_usd`	none	Fail if the run costs more than this, baseline or not.
`compare`	`total`	`total` run cost, or `per_call` average (steadier when the number of tests changes).
`max_feature_increase_pct`	none	Also fail if any single `X-Cost-Feature` rises by more than this.
`min_calls`	`1`	Fewer calls than this is reported as `no_data` and fails.
`settle_seconds`	`10`	Calls are logged just after each response; the check waits (0-30 s) until the run's call count stops changing.
`update_baseline`	`false`	If the check passes (or no baseline exists yet), make this run the baseline.
`commit_sha`, `branch`	none	Shown in the dashboard history.

Results

`status`	`passed`	Meaning
`pass`	true	Within every limit.
`fail`	false	Over a limit. `reasons` says which.
`no_baseline`	true	Nothing to compare with yet (unless `max_cost_usd` was exceeded).
`no_data`	false	The run recorded fewer than `min_calls` calls. Usually a setup problem.

The response also includes the run and baseline totals, the change in percent and a per-feature breakdown. Control → CI Cost Gate shows the history, lets you inspect each check and accept any run as a baseline.

Runs older than 30 days are not considered. Baseline names use letters, digits and . _ -.

Other endpoints

GET /api/cost-gate/checks?limit=50: recent checks
GET /api/cost-gate/baselines: baselines
POST /api/cost-gate/baselines with {"name": "main", "run_id": "..."}: set a baseline from any run
DELETE /api/cost-gate/baselines/{name}