Get usage for a period

GET

api

accounts

{account_id}

billing

usage

Get usage for a period

curl --request GET \
  --url https://app.tied.com/api/v1/accounts/{account_id}/billing/usage \
  --header 'api_access_token: <api-key>'

import requests

url = "https://app.tied.com/api/v1/accounts/{account_id}/billing/usage"

headers = {"api_access_token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {api_access_token: '<api-key>'}};

fetch('https://app.tied.com/api/v1/accounts/{account_id}/billing/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/accounts/{account_id}/billing/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["api_access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/accounts/{account_id}/billing/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("api_access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "schema_version": "1",
  "account_id": 1,
  "period": "month",
  "range_type": "named",
  "custom_from": null,
  "custom_to": null,
  "period_start": "2026-09-01T00:00:00Z",
  "period_end": "2026-10-01T00:00:00Z",
  "timezone": "UTC",
  "previous_period_start": "2026-08-02T00:00:00Z",
  "previous_period_end": "2026-09-01T00:00:00Z",
  "load_state": "degraded",
  "freshness": {
    "source": "clickhouse",
    "as_of": "2026-09-21T04:24:40Z",
    "state": "error",
    "last_ingested_event_at": null,
    "lag_seconds": null
  },
  "reconciliation": {
    "status": "unknown",
    "outbox_totals": {
      "resolutions": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "channel_fees": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "other_variable_usage": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      }
    },
    "analytics_totals": null,
    "drift": {
      "reason": "Billing::ClickhouseClient::ConfigurationError"
    }
  },
  "sections": {
    "resolutions": {
      "title": "Resolutions",
      "state": "empty",
      "rows": [
        {
          "key": "knowledge",
          "label": "Knowledge",
          "count": 0,
          "credits": "0.0",
          "dollars": "0.0",
          "pricing_state": "published",
          "previous_count": 1,
          "previous_credits": "5.0",
          "previous_dollars": "0.35"
        },
        {
          "key": "read",
          "label": "Read",
          "count": 0,
          "credits": "0.0",
          "dollars": "0.0",
          "pricing_state": "published",
          "previous_count": 0,
          "previous_credits": "0.0",
          "previous_dollars": "0.0"
        }
      ],
      "totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "llm_passthrough": {
        "credits": "0.0",
        "dollars": "0.0",
        "byok": false,
        "itemized": [],
        "previous_credits": "0.0",
        "previous_dollars": "0.0"
      },
      "previous_totals": {
        "count": 6,
        "credits": "54.0",
        "dollars": "5.55"
      }
    },
    "channel_fees": {
      "title": "Channel Fees",
      "state": "empty",
      "rows": [
        {
          "key": "amb",
          "label": "Apple Messages",
          "billable_unit": "message",
          "direction": "outbound",
          "count": 0,
          "billable_quantity": "0.0",
          "mixtures": [],
          "subtotals": [],
          "credits": "0.0",
          "dollars": "0.0",
          "previous_count": 1,
          "previous_credits": "1.0",
          "previous_dollars": "0.1"
        },
        {
          "key": "rcs",
          "label": "RCS",
          "billable_unit": "message",
          "direction": "outbound",
          "count": 0,
          "billable_quantity": "0.0",
          "mixtures": [],
          "subtotals": [],
          "credits": "0.0",
          "dollars": "0.0",
          "previous_count": 2,
          "previous_credits": "100.0",
          "previous_dollars": "10.0"
        }
      ],
      "totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "previous_totals": {
        "count": 6,
        "credits": "104.0",
        "dollars": "10.4"
      }
    },
    "other_variable_usage": {
      "title": "Other Variable Usage",
      "state": "empty",
      "rows": [
        {
          "key": "ask_tied",
          "label": "Ask Tied",
          "count": 0,
          "credits": "0.0",
          "dollars": "0.0",
          "previous_count": 0,
          "previous_credits": "0.0",
          "previous_dollars": "0.0"
        }
      ],
      "totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "previous_totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      }
    }
  }
}

{
  "error": "Resource could not be found"
}

Authorizations

api_access_token

string

header

required

This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.

Path Parameters

integer

required

The numeric ID of the account

Query Parameters

period

enum<string>

Named reporting window. Defaults to month.

Available options:

day,

week,

month,

quarter,

year,

custom

Example:

"month"

from

string

Start of a custom window, ISO-8601. Required when period=custom.

string

End of a custom window, ISO-8601. Required when period=custom.

Response

Success

Usage for a period, broken into sections, with the equivalent figures for the previous period alongside each row.

schema_version

string

Version of this payload's shape. Branch on it rather than on field presence.

account_id

integer

The account.

period

string

The window requested.

range_type

string

named for a preset window, custom for an explicit range.

period_start

string

ISO-8601 start of the window.

period_end

string

ISO-8601 end of the window.

previous_period_start

string

Start of the comparison window.

previous_period_end

string

End of the comparison window.

timezone

string

Timezone the windows are expressed in.

load_state

string

loaded, empty or degraded. degraded means some of it came from a fallback source.

freshness

object

Where this answer came from and how current it is. Billing reads several systems, so every response says which one it used — treat state other than fresh as a reason to be careful with the numbers rather than a failure.

Show child attributes

reconciliation

object

Whether the analytics totals agree with what has been written to the ledger. status: "unknown" means the check could not run.

sections

object

One entry per section — resolutions, channel_fees, and so on. Each has a title, a state and rows, and each row carries a key that the drilldown endpoint takes as row_key.

Get usage for a period

curl --request GET \
  --url https://app.tied.com/api/v1/accounts/{account_id}/billing/usage \
  --header 'api_access_token: <api-key>'

import requests

url = "https://app.tied.com/api/v1/accounts/{account_id}/billing/usage"

headers = {"api_access_token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {api_access_token: '<api-key>'}};

fetch('https://app.tied.com/api/v1/accounts/{account_id}/billing/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/accounts/{account_id}/billing/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["api_access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/accounts/{account_id}/billing/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("api_access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "schema_version": "1",
  "account_id": 1,
  "period": "month",
  "range_type": "named",
  "custom_from": null,
  "custom_to": null,
  "period_start": "2026-09-01T00:00:00Z",
  "period_end": "2026-10-01T00:00:00Z",
  "timezone": "UTC",
  "previous_period_start": "2026-08-02T00:00:00Z",
  "previous_period_end": "2026-09-01T00:00:00Z",
  "load_state": "degraded",
  "freshness": {
    "source": "clickhouse",
    "as_of": "2026-09-21T04:24:40Z",
    "state": "error",
    "last_ingested_event_at": null,
    "lag_seconds": null
  },
  "reconciliation": {
    "status": "unknown",
    "outbox_totals": {
      "resolutions": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "channel_fees": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "other_variable_usage": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      }
    },
    "analytics_totals": null,
    "drift": {
      "reason": "Billing::ClickhouseClient::ConfigurationError"
    }
  },
  "sections": {
    "resolutions": {
      "title": "Resolutions",
      "state": "empty",
      "rows": [
        {
          "key": "knowledge",
          "label": "Knowledge",
          "count": 0,
          "credits": "0.0",
          "dollars": "0.0",
          "pricing_state": "published",
          "previous_count": 1,
          "previous_credits": "5.0",
          "previous_dollars": "0.35"
        },
        {
          "key": "read",
          "label": "Read",
          "count": 0,
          "credits": "0.0",
          "dollars": "0.0",
          "pricing_state": "published",
          "previous_count": 0,
          "previous_credits": "0.0",
          "previous_dollars": "0.0"
        }
      ],
      "totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "llm_passthrough": {
        "credits": "0.0",
        "dollars": "0.0",
        "byok": false,
        "itemized": [],
        "previous_credits": "0.0",
        "previous_dollars": "0.0"
      },
      "previous_totals": {
        "count": 6,
        "credits": "54.0",
        "dollars": "5.55"
      }
    },
    "channel_fees": {
      "title": "Channel Fees",
      "state": "empty",
      "rows": [
        {
          "key": "amb",
          "label": "Apple Messages",
          "billable_unit": "message",
          "direction": "outbound",
          "count": 0,
          "billable_quantity": "0.0",
          "mixtures": [],
          "subtotals": [],
          "credits": "0.0",
          "dollars": "0.0",
          "previous_count": 1,
          "previous_credits": "1.0",
          "previous_dollars": "0.1"
        },
        {
          "key": "rcs",
          "label": "RCS",
          "billable_unit": "message",
          "direction": "outbound",
          "count": 0,
          "billable_quantity": "0.0",
          "mixtures": [],
          "subtotals": [],
          "credits": "0.0",
          "dollars": "0.0",
          "previous_count": 2,
          "previous_credits": "100.0",
          "previous_dollars": "10.0"
        }
      ],
      "totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "previous_totals": {
        "count": 6,
        "credits": "104.0",
        "dollars": "10.4"
      }
    },
    "other_variable_usage": {
      "title": "Other Variable Usage",
      "state": "empty",
      "rows": [
        {
          "key": "ask_tied",
          "label": "Ask Tied",
          "count": 0,
          "credits": "0.0",
          "dollars": "0.0",
          "previous_count": 0,
          "previous_credits": "0.0",
          "previous_dollars": "0.0"
        }
      ],
      "totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      },
      "previous_totals": {
        "count": 0,
        "credits": "0.0",
        "dollars": "0.0"
      }
    }
  }
}

{
  "error": "Resource could not be found"
}

Getting started

Conversations

Contacts

Inboxes and channels

Automation and routing

Reporting

Help Center

Account and access

Billing

Client API

Widget API

Receiving webhooks

Get usage for a period

Authorizations

Path Parameters

Query Parameters

Response