Manage HtAG API and MCP costs: plan, limit and refresh your data

A useful HtAG workflow starts with a cost plan. Whether you call the API directly or let an AI assistant use MCP tools, decide what data you need, how many rows it can return and how often you will refresh it before execution.

This guide expands the billing introduction sent to new Developer Portal accounts. It covers funding, billing units, bounded requests, caching and AI tool controls. Keep the current portal rate card and API reference beside you: prices and request contracts can change.

1. Check funding and account access first

Open Billing in the Developer Portal before making requests. The welcome email instructs new accounts to add funds before requests are processed; follow the funding requirement shown for your account. Check your balance and account readiness before starting a scheduled job or an AI workflow.

The published data pricing includes a one-time free allowance for each endpoint: 25 returned rows, or 25 requests for Reference lookups billed per request. A free allowance and the requirement to fund an account are separate questions. Do not assume an allowance removes the portal’s funding prerequisite. HtAG agent executions have no free allowance.

Check which HtAG plan is linked to your developer account and whether a discount applies. Use the account’s displayed eligibility rather than assuming your website membership and developer usage are already linked.

2. Know the unit you are paying for

• Data APIs and MCP data tools: generally charged by returned rows, at the endpoint’s assigned tier.
• Reference lookup exceptions: some are billed per request. Check the specific endpoint’s billing unit.
• HtAG research agents: charged per execution, rather than the underlying data row count.

An HTTP call, a tool invocation and a billable row are not interchangeable. One time-series call can return many time points. A batch or spatial search can return many records. Several paginated calls can form one user-visible workflow. An AI client’s own model or platform charges are separate from HtAG usage.

Published list rates checked on 2 October 2026 are A$0.0020 for Reference, A$0.031 for Standard, A$0.075 for Enhanced, A$0.121 for Premium and A$0.222 for Restricted, including GST. These are baseline figures, before applicable allowances and discounts. The endpoint determines its tier; selecting a smaller result does not change that tier.

3. Write an endpoint-by-endpoint cost plan

For every proposed operation, record the endpoint or agent, billing unit, tier or execution rate, filters, expected units, maximum units, refresh frequency and subtotal. Include each page, each metric and each geography in the plan.

Baseline data estimate = billable returned rows × applicable per-row rate. For request-billed lookups, use requests; for agents, use executions. Sum the operations to estimate the workflow. For recurring jobs, multiply by planned runs, then account for extra pages and permitted retries.

Keep expected cost and worst-case planned cost separate. A small response today does not guarantee the same row count next month. A per-request limit also does not cap a workflow that automatically requests more pages.

Worked examples at published list rates

• A Premium shortlist: 20 billable rows × A$0.121 = A$2.42. Running that same 20-row retrieval daily for 30 days would be A$72.60 before discounts or allowances.
• Four slope results for one area and property type: Supply LS, Supply SS, Demand LS and Demand SS normally return one Premium row each. Four rows × A$0.121 = A$0.484.
• A Restricted monthly history: 60 billable time points × A$0.222 = A$13.32 for one metric, area and property type. Ten such areas at the same horizon would be 600 rows, or A$133.20.

These are illustrations of billable units, not quotes or a claim that a fresh account pays every illustrated row. Apply only the allowances and discounts that actually remain or apply to your account. Check the returned shape: extra property types, bedroom selections or geographies can multiply the result.

4. Bound the request and the whole workflow

• Start with one area, address or short property list and the filters that answer your question.
• Where supported, set limit and offset explicitly. Check their meaning, maximum and ordering in that endpoint’s reference.
• For a Market Query shortlist, start with 10–20 rows and inspect the first response before expanding.
• Set a maximum page count and a total row budget across all pages. Stop when either is reached.
• Limit history to the required horizon using supported parameters. Do not assume every endpoint accepts a date filter or pagination controls.
• Keep retries bounded. Log failures, distinguish authentication or validation problems from temporary failures, and avoid repeatedly resubmitting an unchanged invalid request.

Published monthly endpoint caps are access limits, not a spending budget you choose. Restricted data endpoints have a 10,000-row monthly cap per endpoint; other endpoints have their own limits. Check the schedule before designing a bulk workload. Put your own budget checks in your application or tool policy, and confirm any account-level spend control in the portal before relying on it.

5. Choose summaries when the question is about direction

If you only need long- and short-term supply or demand direction, consider /v1/markets/supply/ls, /v1/markets/supply/ss, /v1/markets/demand/ls and /v1/markets/demand/ss. These Premium slope results can avoid retrieving every point in a Restricted history.

A slope summary and a full history answer different questions. Use the full series when you need to chart individual periods, audit a turning point or perform your own analysis. Choose based on the task, then compare planned row counts and rates. Keep the Data Dictionary handy for metric interpretation.

6. Cache deliberately and refresh the right way

Store a retrieved snapshot with its endpoint, input filters, area or address identifier, property selection, reporting period and retrieval time. Re-score or reformat that snapshot locally when only your assumptions or presentation change. Check applicable storage and reuse terms for your data access.

Static histories: backfill, then append

For static historical metrics such as Days on Market and Stock on Market, retrieve the required series once and store it. Later monthly refreshes can request only unstored periods using the endpoint’s supported controls. After the initial backfill, this is normally one new monthly row per metric, area and property type.

Confirm ordering and pagination before calculating an offset: a newest-first response moves older records as new ones arrive. Deduplicate by reporting period and selection, check for gaps and allow for delayed records. “Append” describes your storage strategy, not an instruction to increment an offset blindly.

Revisionary histories: refresh the required horizon

Typical price, rent, yield and years-to-own histories can revise earlier values. Appending only the newest point can leave your stored chart out of date. Re-retrieve the full horizon required by your product, with explicit supported bounds, and replace or upsert the affected periods. Budget for that refresh as a recurring workload.

A cached result is not current merely because it is available. Show its reporting period and refresh time, and choose a refresh schedule that suits the user question.

7. Give an AI assistant a cost policy before access

Give your assistant the live pricing page and API reference before it plans tool calls. Ask for a plan first and require a new approval when it needs more pages, a wider search, retries or Restricted data. A prompt is an instruction; application-enforced row, page and retry limits provide stronger control.

A prompt you can reuse

Before calling any HtAG tool, read the current pricing and API reference. Produce a table with each endpoint or agent, billing unit, tier, filters, expected and maximum units, refresh frequency, expected cost and maximum planned cost. Use my budget of [AUD amount] for this workflow. Start with one bounded request and no automatic pagination. Do not retry, broaden the geography, extend the history, call Restricted endpoints or run another agent without showing the additional cost and asking me first. Reuse an appropriate stored snapshot where possible. After execution, report the returned rows or executions and stop if the next operation would exceed the approved plan.

Supply a real budget and task scope before using the prompt. Do not give the assistant credentials until your connection is configured securely; see the MCP setup guide and API setup guide.

8. Review usage after the first run

Compare your plan with the rows or executions returned and the usage recorded in the Developer Portal. Log endpoint, filters, result count, pages, retries and timing in your application, without recording API secrets. Reconcile your estimate with actual account charges before scaling the workflow.

If usage is higher than expected, check broad defaults, automatic pagination, multiple selections, agent reruns and repeated refreshes. Pause the recurring job while you identify the cause. Review current volume bands, linked-plan eligibility or negotiated terms when usage grows; do not assume discounts stack.

Track actual charges from response headers

Every successful 2xx response from a billable endpoint carries billing telemetry headers. Read these from the response to drive per-call charge-back, usage dashboards or balance monitoring, without a separate API call.

Header	Example	Meaning
X-Billing-Cost	0.136	Amount charged for this request, in AUD.
X-Billing-Balance	49.864	Account balance in AUD after this deduction.
X-Billing-Units	4	Billable units counted: rows, addresses or properties, depending on the endpoint.
X-Billing-Tier	tier1	Applied billing tier: free, tier1, tier2 or tier3.
X-Billing-Free-Remaining	21	Free-tier units remaining on the account. Absent when no free allowance applies.
X-Billing-Free-Granted	1	Free-tier units consumed by this request. Absent when no free allowance applies.

The examples illustrate header values; use the values on your actual response. X-Billing-Cost is a decimal string in AUD. There is no separate credit currency, and the account balance is also in AUD. Keep the telemetry tier exactly as returned; do not assume its tier1/tier2/tier3 labels map directly to the named Reference, Standard, Enhanced, Premium and Restricted endpoint tiers.

Non-2xx responses, including 4xx and 5xx, are not charged and do not carry these headers. Record their status separately. An absent header is not the same as a recorded zero charge: free-allowance headers are optional, and only successful billable responses carry the telemetry.

Read the headers in Python

# response is the result of your existing HtAG request.
from decimal import Decimal

if 200 <= response.status_code < 300:
    cost_aud = response.headers.get("X-Billing-Cost")
    if cost_aud is not None:
        billing = {
            "cost_aud": Decimal(cost_aud),
            "balance_aud": response.headers.get("X-Billing-Balance"),
            "units": response.headers.get("X-Billing-Units"),
            "tier": response.headers.get("X-Billing-Tier"),
            "free_remaining": response.headers.get("X-Billing-Free-Remaining"),
            "free_granted": response.headers.get("X-Billing-Free-Granted"),
        }
        # Persist billing with your workflow ID and endpoint, never your API key.

Read the headers in browser JavaScript

The API already exposes these headers through its Access-Control-Expose-Headers policy, so browser fetch and XHR clients can read them.

// response is the result of your existing fetch request.
if (response.ok) {
  const costAUD = response.headers.get("X-Billing-Cost");
  if (costAUD !== null) {
    const billing = {
      costAUD,
      balanceAUD: response.headers.get("X-Billing-Balance"),
      units: response.headers.get("X-Billing-Units"),
      tier: response.headers.get("X-Billing-Tier"),
      freeRemaining: response.headers.get("X-Billing-Free-Remaining"),
      freeGranted: response.headers.get("X-Billing-Free-Granted"),
    };
    // Store decimal strings; use decimal-safe arithmetic when totalling costs.
  }
}

Header accessibility does not make an API key safe to expose in a public frontend. Follow your authentication architecture and retain billing headers in your backend when it makes the request. If an MCP client hides HTTP headers, capture telemetry at a layer that has access to the API response rather than asking the assistant to infer a charge.

Attach each charge to a workflow or customer identifier in your own logs and total the actual X-Billing-Cost values. Use the post-request balance to decide whether to pause the next operation. With concurrent requests, balance snapshots can arrive out of order; reconcile totals and the portal balance rather than treating the last response received as the newest account state.

Your cost-management checklist

• Billing is ready and the account’s applicable rates are checked.
• Every operation has a known billing unit, expected count and maximum count.
• Pages, retries, history and refresh frequency are bounded.
• Static and revisionary series use different refresh strategies.
• AI tools follow an approved plan, with application limits where available.
• The first run is reconciled before the workload expands.

Return to the Get started guide for the full onboarding collection. For current charges and access, use Billing, the portal rate card and the public pricing schedule.