Skip to main content

Cost Envelope

Every metered data call on the platform charges two things: the Alien fee (a flat per-call platform fee) and, when the data belongs to another organization and carries a price, a royalty paid to that data owner. Until recently the caller received the data but was told nothing about the amount. The cost envelope closes that gap: every metered response carries the exact amounts that were written to the ledger for that call, so a client, an AI agent or a chat UI can add up its own spend as it goes.

The envelope is read from the ledger, never recomputed. What you see on the response is what was debited from your organization.

Shape​

An envelope is a JSON array with one line per currency actually charged:

[
  { "currency": "EUR", "royalty": 0.00536121, "alienFee": 0.01, "total": 0.01536121 }
]
FieldTypeMeaning
currencyISO 4217 codeThe currency this line is denominated in.
royaltynumberRoyalties paid to data owners in this currency for this call. 0 when no priced third-party data was served.
alienFeenumberThe platform fee charged in this currency.
totalnumberroyalty + alienFee for this line only.

Rules worth knowing:

  • Amounts are rounded to 8 decimal places at every step, so a line's total always equals the rounded sum of its parts.
  • The Alien fee is always charged in the platform currency (EUR). A royalty is charged in the currency of the dataset's price. A call that touches a USD-priced dataset therefore produces two lines, EUR for the fee and USD for the royalty. Nothing is ever summed across currencies; a single scalar total would be wrong.
  • Lines are unique per currency and sorted by currency code.
  • Your own data is free of royalties. When the consuming organization also owns the dataset, the royalty line shows 0 even though the dataset carries a price. The fee still applies.
  • An empty array [] is a real value: the call was metered and nothing was charged (for example a connector call whose upstream answered with an error).

On the HTTP API​

Every metered route returns the envelope in the x-cost-envelope response header as the JSON above. Routes whose response body the platform owns also repeat it as a top-level cost field in the JSON body. The header and the body field are always byte-identical.

Route familyHeaderBody cost
Cluster data: GET /clusters/listDatasets, GET /clusters/getDataset/{id}, POST /clusters/keywordSearch, POST /clusters/vectorSearchChunks, GET /clusters/getEntryContent/{id}, GET /clusters/getEntryDocuments/{id}yesyes
GET /clusters/getEntryFile/{id} (binary download)yesno, the body is the file
Cluster proxy: /clusters/{clusterId}/proxy/api/v1/entries/{id}/content, /clusters/{clusterId}/proxy/api/v1/search and the vector search pathsyesno, the body is relayed from the cluster
Connector proxy: /external-apis/{connectorId}/proxy/{path}yesno, the body is relayed from the external API

Example, a keyword search across two clusters where one of the datasets is priced by another organization:

curl -i -X POST https://api.alien.club/clusters/keywordSearch \
  -H "Authorization: Bearer $ALIEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "cancer", "clusterIds": [76], "limit": 5}'
HTTP/2 200
x-cost-envelope: [{"currency":"EUR","royalty":0.00536121,"alienFee":0.01,"total":0.01536121}]
x-request-id: 4740e12c-023c-97fa-b2d6-8191d3b74b24

{"success": true, "data": {"results": {...}, "errors": {}},
 "cost": [{"currency":"EUR","royalty":0.00536121,"alienFee":0.01,"total":0.01536121}]}

The same search against a cluster your organization owns yields "royalty": 0 with the fee unchanged. A metadata-only call such as getDataset or listDatasets has no royalty component either, since no priced content is served.

Error responses​

The envelope follows the ledger, so it also appears on error responses when something was charged:

  • A cluster route that relays an upstream error (for example a 404 from the cluster for a wrong file name) still carries a fee-only envelope, because the platform fee is charged on every cluster call.
  • A connector proxy call whose external API answers with a non-2xx status carries []: the fee is only charged when the external call succeeds.
  • When the platform rejects a call before any metering runs (a validation error, an unknown connector endpoint, a permission denial), there is no x-cost-envelope header at all. Absent means "not metered", [] means "metered, nothing charged".

Cross-origin callers​

The response exposes x-cost-envelope, x-request-id and x-data-tokens through Access-Control-Expose-Headers, so a browser application can read them with fetch or XMLHttpRequest.

Data tokens​

Connector proxy responses also carry x-data-tokens, the number of data tokens counted on the relayed body. Dataset and endpoint prices are expressed per million data tokens, so royalty on a line is the price of the data served times the tokens counted, in the price's currency.

In MCP tool results​

When an AI agent reaches the platform through an Alien MCP server (the unified mcp.alien.club server or a per-cluster data server, see AI Agent Integration), every metered tool call returns the envelope in the tool result's _meta under the key alien.club/cost:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{ \"success\": true, \"data\": { ... } }" }],
    "isError": false,
    "_meta": {
      "alien.club/cost": [
        { "currency": "EUR", "royalty": 0.00293695, "alienFee": 0.01, "total": 0.01293695 }
      ]
    }
  }
}

Two design points matter for agent builders:

  • The model never sees the cost. The envelope rides in _meta, which MCP clients do not feed into the model's context, and the tool's text content does not contain it. Cost is for the host application, not for the assistant's reasoning.
  • The key is present on every metered tool call, including results flagged isError when a fee was charged. A tool that never touched a metered route has no alien.club/cost key at all. Detect an Alien MCP server by the presence of the key, not by its URL.

Tools that only read metadata (datacluster_list_datasets, datacluster_get_dataset, datacluster_get_entry_documents) report a fee-only line; tools that serve content or search (datacluster_keyword_search, datacluster_vector_search_chunks, datacluster_get_entry_content, datacluster_get_entry_file) add the royalty when the data is priced and owned by someone else.

In the chat SDK​

@alien_intelligence/chat-sdk 0.12.0 and later reads alien.club/cost from every MCP tool result and exposes it at three levels, all typed as CostEnvelope (ReadonlyArray<CostLine>):

WhereFieldMeaning
tool-result stream eventcostThe envelope of that single tool call.
ToolPartEntry (a tool call inside an assistant turn)costPersisted with the turn, so it survives a reload or a resume. undefined = never reported, [] = metered and free.
AssistantTurncostDerived over the turn's tool calls.
useChat() return valuesessionCostLive session total derived over every assistant turn. null while nothing in the session has ever been reported.

Totals are always produced by merging envelopes per currency (mergeCostEnvelopes / deriveCost), never by accumulating a running number, so a session that touched EUR and USD data shows two lines. Helper exports: parseCostEnvelope, readCostMeta, mergeCostEnvelopes, deriveCost, roundAmount, and the constant COST_META_KEY.

const { turns, sessionCost } = useChat({
  endpoint: "/api/chat",
  onWarn: warning => logger.warn(warning),
})

// Render one line per currency, never a cross-currency sum
sessionCost?.map(line => (
  <span key={line.currency}>
    {line.total.toFixed(4)} {line.currency}
  </span>
))

If a server returns a malformed envelope, the SDK drops it, leaves the entry's cost unset and reports a tool-result-cost-invalid warning through onWarn. It never throws and never lets a bad envelope interrupt the conversation.