Research Endpoints

Research is part of All tools. A start needs the relevant scope and enough credits, and the tool must be available in /v1/health. Free credits also follow the free limits. Accepted starts return 202 Accepted.

Research endpoints create cited reports from a customer question. Research is preview, always asynchronous, billable, callback-capable, and dry-run capable. It needs a plan or bought credits (a credit pack): free credits (the guest trial and the signup bonus) do not cover it, and a start on free credits returns operation_not_available_on_free. Comprehensive mode is Scale only.

POST/v1/research/deep

Create a deep research operation.

curl -X POST https://www.chab.ai/v1/research/deep \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-deep-001" \
  -d '{
    "question": "Compare the public API reliability practices of three payment platforms.",
    "mode": "quick",
    "source_budget": 10,
    "max_credit_budget": 210,
    "report_format": "markdown",
    "source_guidance": {
      "source_types": ["documentation", "company_site"],
      "language": "en",
      "recency_days": 365
    }
  }'

Required scope: api:research:write.

Live requests require Idempotency-Key. Idempotent retries with the same key and exact same body return the original operation. Reusing the key with a different body returns idempotency_key_conflict.

Request Fields

The quick example above fits the default Pro operation spend threshold. Standard research needs a larger hold than the default Pro threshold, so a Pro team must raise its threshold on the credits usage page before starting it. Available credits and API-key budgets still apply; raising a threshold does not buy credits.

Unsupported provider-shaped fields such as model IDs, provider IDs, raw tools, browser controls, vector stores, function calling, structured-output controls, and nested callback objects are rejected with validation_failed.

Source Guidance

source_guidance may include:

{
  "domains": ["example.com", "docs.example.com"],
  "source_types": ["web", "news", "academic", "documentation", "government", "company_site"],
  "language": "en",
  "region": "US",
  "recency_days": 365
}

Chab reports whether guidance was applied, partially applied, or unsupported. Guidance is best-effort; it does not force provider-side browsing behavior.

Dry Run

Dry run validates request shape, plan access, rate/usage limits, callback preview, service readiness, spend threshold, and credit availability. It does not create an idempotency row, operation, billing hold, background job, callback secret, artifact, risk signal, notification, or rate-bucket hit.

curl -X POST https://www.chab.ai/v1/research/deep \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "question": "Summarize developer adoption signals for database branching tools.",
    "mode": "quick",
    "source_budget": 5,
    "max_credit_budget": 210
  }'

{
  "data": {
    "operation_key": "research.deep",
    "family": "research",
    "estimated_credits": 210,
    "currency": "credit",
    "mode": "quick",
    "source_budget": 5,
    "max_credit_budget": 210,
    "report_format": "markdown",
    "pricing_class": "research-compact",
    "question": {
      "characters": 66,
      "content_redacted": true
    },
    "source_guidance": {
      "provided": false,
      "domain_count": 0,
      "source_types": [],
      "language": null,
      "region": null,
      "recency_days": null
    },
    "callback": {
      "requested": false,
      "enabled": false,
      "url": null,
      "events": [],
      "notify_on_expiration": false,
      "secret_staged": false
    },
    "live_request": {
      "requires_idempotency_key": true
    }
  },
  "meta": {
    "request_id": "req_123",
    "dry_run": true
  }
}

Accepted Response

{
  "operation": {
    "id": "op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "status": "queued",
    "operation_key": "research.deep",
    "family": "research",
    "status_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "result_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/result",
    "estimated_credits": 210,
    "result_available": false
  },
  "meta": {
    "request_id": "req_123",
    "credits": {
      "estimated": 210,
      "reserved": 210,
      "currency": "credit"
    }
  }
}

Poll the operation status URL, use one-off callbacks, or fetch the result URL after the operation succeeds.

Result Shape

Successful results include the report, retained sources, linked citations, source-guidance handling, usage, budget metadata, runtime metadata, warnings, and artifacts.

{
  "data": {
    "operation_id": "op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "operation_key": "research.deep",
    "status": "succeeded",
    "result": {
      "report": {
        "format": "markdown",
        "inline": true,
        "content": "Payment platforms publish reliability practices around idempotency, webhook replay, and status pages.",
        "artifact_role": null
      },
      "sources": [
        {
          "id": "src_001",
          "marker": "[1]",
          "url": "https://example.com/docs/reliability",
          "title": "Reliability practices",
          "source_type": "documentation",
          "published_at": null,
          "accessed_at": "2026-07-14T12:00:00+00:00"
        }
      ],
      "citations": [
        {
          "source_id": "src_001",
          "marker": "[1]",
          "url": "https://example.com/docs/reliability",
          "title": "Reliability practices",
          "start_index": 0,
          "end_index": 66,
          "claim": "Payment platforms publish reliability practices around idempotency"
        }
      ],
      "source_guidance": {
        "handling": "applied",
        "best_effort": true
      },
      "usage": {
        "pricing_class": "research-compact",
        "input_tokens": 1200,
        "output_tokens": 900,
        "cached_input_tokens": 0,
        "reasoning_tokens": 0,
        "sources_analyzed": 1
      },
      "budget": {
        "max_credit_budget": 210,
        "incurred_credits": 12,
        "currency": "credit",
        "exhausted": false
      },
      "runtime": {
        "timed_out": false,
        "provider_status": "completed",
        "completed_at": "2026-07-14T12:00:05+00:00"
      },
      "artifacts": []
    },
    "warnings": [
      {
        "code": "field_unavailable",
        "message": "published_at is not available for retained research sources.",
        "field": "sources.published_at",
        "severity": "info"
      }
    ],
    "artifacts": []
  },
  "meta": {
    "request_id": "req_123"
  }
}

published_at is currently always null for retained research sources. Chab emits field_unavailable warnings when normalized fields are unavailable. Citation start_index and end_index are zero-based Unicode character offsets into report.content (end exclusive), not byte offsets.

Artifacts

Small reports and sources are returned inline. Large reports create two protected customer-visible artifacts:

• research_report: the report as Markdown or JSON.
• research_sources_export: the retained source list as JSON.

research_report can be reused as operation input only when a consuming operation supports the artifact MIME type. research_sources_export is download-only and cannot be used as an operation input source.

Pricing

Research reserves the full accepted max_credit_budget before work starts.

Each mode uses its own internally selected model with at most two web-search tool calls and 8,192 total output tokens, including reasoning; a smaller sufficiently funded hold may permit one tool call. The initial paid two-search holds are at least 210 credits for quick, 2,070 for standard, and 4,130 for comprehensive; Chab refuses a lower-than-safe hold before provider dispatch (research_budget_exhausted). These holds cover the bounded provider work; they are not an exchange rate and do not change the metered token/source tariff below. If an output-limited response still contains a usable cited report, Chab returns it with a partial_results warning; otherwise it fails rather than presenting an uncited result. Source budgets remain ceilings, not promises of that many searches or sources.

Research creation is not automatically repeated after an uncertain connection loss, timeout or server error: the provider may already have accepted the background task. Such work keeps its credit hold until the outcome is known; a dropped connection does not prove that the provider did no work. If a started response's cost cannot be measured, the reserved credits remain a hold while Chab checks the bound provider response and reviews the case. Chab charges only when matching usage or provider billing records confirm the cost; if the cost still cannot be confirmed after the review window, Chab drops the charge and releases the hold. Cancellation does not turn an unknown cost into a free result. Final settlement uses actual normalized usage and retained cited source count, capped at the reserved budget:

research-compact = ceil(input_tokens * 2 / 1000 + output_tokens * 8 / 1000 + sources_analyzed * 2)
research-deep    = ceil(input_tokens * 4 / 1000 + output_tokens * 16 / 1000 + sources_analyzed * 4)

sources_analyzed is the count of unique retained cited source URLs after source_budget truncation. It is not a promise about provider browsing volume. Unused reserved credits are released at settlement.

Cancellation before provider work starts releases the hold. Cancellation after provider work starts may charge recorded actual work up to the active hold.

Timeouts and Partial Results

Research uses the standard operation lifecycle and hard runtime ceiling. The adapter also has a soft timeout before the hard ceiling so it can retrieve current state and either return a partial success with partial_results or end with research_timeout.

When a progress estimate would exceed the accepted max budget, Chab stops safely. If a usable cited report exists, the operation succeeds with partial_results and budget.exhausted=true. If no usable cited report can be produced, the operation fails with research_budget_exhausted.

Research Errors

Validation failures, missing budgets, unsupported fields, nested callbacks, source-budget range failures, and comprehensive mode on non-Scale plans use validation_failed with field details.