DATAGOATDocsQuick startConnectKeys

Quick start

A free test key, a first answer, and a check that the answer is genuine. The test key works on the free sample records, so you need no data of your own.

1. Get a key

pip install datagoat
datagoat signup        # saves a free test key (dgk_test_…) for the samples

Without Python:

curl -s -X POST https://api.datagoat.io/v1/agents/register
# {"api_key": "dgk_test_…", …}   shown once

For your own data, sign in at datagoat.io/keys and create a live key (dgk_live_…). Set it as DATAGOAT_API_KEY.

2. Ask

Every call sends a record, questions and cases:

  • sample:saas_churn is the record: 800 synthetic SaaS accounts, with a yes/no churned column.
  • churn is the question id. The answer comes back under the same id.
  • cust_0001 is the case.

API

curl https://api.datagoat.io/v1/ask \
  -H "Authorization: Bearer $DATAGOAT_API_KEY" -H "Content-Type: application/json" \
  -d '{"data": {"dataset_id": "sample:saas_churn"},
       "entity_column": "customer_id", "subject_kind": "org",
       "questions": {"churn": {"type": "yesno", "outcome_column": "churned", "outcome_is_desirable": false}},
       "cases": {"ids": ["cust_0001"]}}'

Python

from datagoat import Client, yesno

dg = Client()          # DATAGOAT_API_KEY, or the key `datagoat signup` saved
out = dg.ask({"churn": yesno("churned", outcome_is_desirable=False)},
             dataset_id="sample:saas_churn", entity_column="customer_id", subject_kind="org",
             cases={"ids": ["cust_0001"]})
print(out["answers"]["churn"]["cases"][0]["p"])     # 0.7005

TypeScript

import { Datagoat, yesno } from "@datagoat/sdk";

const dg = new Datagoat({ apiKey: process.env.DATAGOAT_API_KEY! });
const out = await dg.ask({ churn: yesno("churned", { outcome_is_desirable: false }) }, {
  data: { dataset_id: "sample:saas_churn" }, entity_column: "customer_id", subject_kind: "org",
  cases: { ids: ["cust_0001"] },
});

An AI assistant (MCP)

Add https://api.datagoat.io/mcp as a connector in Claude, ChatGPT, Cursor or VS Code (Connect). Then ask: "Using Datagoat on sample:saas_churn, how likely is cust_0001 to churn, and why?"

3. Read the answer

The answer, with numbers shortened:

{
  "status": "done",
  "answers": {
    "churn": {
      "type": "yesno",
      "state": "answered",
      "quality": {"realised_lift": 4.48, "top_decile_lift": 4.44, "validation_scheme": "holdout", "confidence_tier": "high"},
      "cases": [{
        "entity_id": "cust_0001",
        "p": 0.7005,
        "reasons": [
          {"feature_label": "logins_last_30d", "value": 11,     "likelihood_direction": "higher", "strength": "strong"},
          {"feature_label": "tenure_months",   "value": 21,     "likelihood_direction": "higher", "strength": "strong"},
          {"feature_label": "support_tickets", "value": 12,     "likelihood_direction": "higher", "strength": "moderate"},
          {"feature_label": "monthly_charges", "value": 171.02, "likelihood_direction": "higher", "strength": "moderate"}
        ]
      }],
      "verdicts": [{"verdict": {"…": "…"}, "signature": {"…": "…"}}]
    }
  },
  "fits_run": 1,
  "billable_decisions": 1
}

Read state first. answered means the record supports an answer. p is the chance that cust_0001 churns: 70%. The reasons are the columns that pushed it up. billable_decisions counts the answered case, though samples are never charged. quality shows how well the model did on rows it never saw: the riskiest tenth of those accounts churned at 4.44 times the average rate. More in Answers.

Ask again and nothing refits: fits_run is 0 and every number is the same.

4. Verify

dg.verify_all(out)     # True: every Verdict in the answer is genuine

Verification is free and needs no key.

Next