Usage aggregates

Read-only account aggregates. The path has no account ID, but required query account_id is resolved by EnsureCurrentAccountHelper into Current.account after membership validation; this is not session-only resolution. Requires a User membership with administrator or manager role. Foreign, nonexistent and omitted account IDs return the same 401 access denial for a signed-in user. period_start is inclusive and period_end exclusive, at most 366 days apart. Defaults to resolutions grouped by resolution_class,resolver,outcome; usage defaults to period_bucket,channel_type,billing_unit. Grouping dimensions must be unique. Usage supports period_bucket,channel_type,billing_unit,provider,carrier,direction,country; resolutions supports resolution_class,resolver,outcome. channel is usage-only. A persisted UTC calendar-month snapshot is used when available (latest by default); version requires exactly a calendar month and an existing version. Otherwise queries live analytics. Empty groups return data [] with has_more false. Topics enablement does not gate this endpoint. Provider unavailability or malformed analytics data returns 503. P2 owns the broader account-resolution review.

GET

api

analytics

usage-aggregates

Usage aggregates

curl --request GET \
  --url https://app.tied.com/api/v1/analytics/usage-aggregates \
  --header 'api_access_token: <api-key>'

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

fetch('https://app.tied.com/api/v1/analytics/usage-aggregates', 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/analytics/usage-aggregates")

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/analytics/usage-aggregates"

	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_start": "2026-08-01T00:00:00Z",
  "period_end": "2026-09-01T00:00:00Z",
  "metric": "resolutions",
  "group_by": [
    "resolution_class",
    "resolver",
    "outcome"
  ],
  "data": [
    {
      "dimensions": {
        "resolution_class": "read",
        "resolver": "orch_agent",
        "outcome": "confirmed"
      },
      "quantity": "1.00000000"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "has_more": false
  },
  "frozen": true,
  "snapshot": {
    "version": 1,
    "latest_version": 1,
    "closed_at": "2026-10-07T12:00:00Z",
    "reason": "period_close",
    "supersedes_version": null
  }
}

{
  "error": {
    "code": "multiple_credentials"
  }
}

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

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

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

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

{
  "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.

Query Parameters

account_id

integer

required

Account to resolve through the authenticated caller membership.

period_start

string<date-time>

required

Inclusive ISO 8601 start.

period_end

string<date-time>

required

Exclusive ISO 8601 end; maximum interval 366 days.

metric

enum<string>

default:resolutions

Aggregate measure.

Available options:

usage,

resolutions

group_by

string

Comma-separated dimension names; must be unique.

channel

string

Optional usage channel filter from the supported channel types.

version

integer

Positive persisted snapshot version.

Required range: x >= 1

page

integer

default:1

One-based page.

Required range: x >= 1

per_page

integer

default:50

Rows per page.

Required range: 1 <= x <= 100

Response

Actual synthetic request response; see topic analytics evidence.

Versioned account-scoped usage or resolution aggregates.

schema_version

enum<string>

required

Aggregate schema version.

Available options:

1

account_id

integer

required

Account resolved from the required account_id query parameter after membership checks.

period_start

string<date-time>

required

Inclusive period start.

period_end

string<date-time>

required

Exclusive period end.

metric

enum<string>

required

Measure being aggregated.

Available options:

usage,

resolutions

group_by

string[]

required

Effective grouping dimension names.

Grouping dimension.

data

object[]

required

One page of groups; empty data means no groups.

Show child attributes

pagination

object

required

Pagination.

Show child attributes

frozen

boolean

required

True when served from an account-scoped persisted monthly snapshot.

snapshot

object | null

required

Snapshot metadata, or null for live periods.

Show child attributes

Usage aggregates

curl --request GET \
  --url https://app.tied.com/api/v1/analytics/usage-aggregates \
  --header 'api_access_token: <api-key>'

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

fetch('https://app.tied.com/api/v1/analytics/usage-aggregates', 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/analytics/usage-aggregates")

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/analytics/usage-aggregates"

	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_start": "2026-08-01T00:00:00Z",
  "period_end": "2026-09-01T00:00:00Z",
  "metric": "resolutions",
  "group_by": [
    "resolution_class",
    "resolver",
    "outcome"
  ],
  "data": [
    {
      "dimensions": {
        "resolution_class": "read",
        "resolver": "orch_agent",
        "outcome": "confirmed"
      },
      "quantity": "1.00000000"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "has_more": false
  },
  "frozen": true,
  "snapshot": {
    "version": 1,
    "latest_version": 1,
    "closed_at": "2026-10-07T12:00:00Z",
    "reason": "period_close",
    "supersedes_version": null
  }
}

{
  "error": {
    "code": "multiple_credentials"
  }
}

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

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

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

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

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

Getting started

Conversations

Contacts

Inboxes and channels

Automation and routing

Reporting

Help Center

Account and access

Orchestration Studio

Billing

Client API

Widget API

Receiving webhooks

Usage aggregates

Authorizations

Query Parameters

Response