Universes

A universe is a named list of assets — bytetrend, for example, or bytefolio, the holdings of a ByteTree portfolio. Use one to narrow other requests to its members, or to see group figures for just those assets. This endpoint lists every universe and how many assets each contains.

Membership is explicit and carried on the asset: every asset record lists the universes it belongs to under universes[] (see List Assets), and ?universe=<slug> on the asset and metric endpoints filters to that membership. The group metric routes aggregate a universe’s members across the five global dimensions.

Universes and dimensions are independent: dimensions are defined once, globally, and apply identically to every universe. The whole tracked set — every asset regardless of universe — is aggregated separately as the Macro Dataset. macro is not a universe slug.

Every api+mcp key reaches every universe; there is no per-key universe scope. See Authentication.

“Screens” is a subscription tier, not a universe. On your ByteTrend.io account, Screens names a subscription tier — in-product viewing only, the view capability — and does not by itself grant API or MCP access. Elsewhere in this documentation screen is an unrelated technical term for a ranked selection of assets. The tier that reaches this API and the ByteTree MCP is Analyst (API + MCP) (the api+mcp capability described in Authentication).

The roster

bytetrend is the permanent universe: every tracked asset of the types in its rule (stocks, ETFs, crypto and commodities today). The others are portfolio-led or curated baskets — bytefolio, for example — and the set changes over time as ByteTree adds, enables or retires them.

So don’t hard-code the list: read the live roster from GET /api/universes, which returns each universe’s slug, label, source (how its membership is decided) and memberCount.

GET /api/universes lists a universe as soon as it is enabled, even before it has members — expect memberCount: 0 on a basket that is still being filled. ByteTree MCP’s list_grouping_configs serves the same roster but only its populated universes, so a basket can appear in the API before it appears in the MCP.

Universe slugs are the values path segments and universe parameters take; an unknown slug returns 404 on a path and 400 on a parameter; the 400 names the valid slugs, the 404 does not — read them from GET /api/universes.

List Universes

curl https://api.bytetree.io/api/universes \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.bytetree.io/api/universes", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" },
});
const body = await res.json();

import requests

res = requests.get(
    "https://api.bytetree.io/api/universes",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
body = res.json()

{
  "count": 7,
  "total": 7,
  "limit": 500,
  "offset": 0,
  "data": [
    {
      "universe": "bytetrend",
      "label": "ByteTrend",
      "source": "rule",
      "rule": { "assetTypes": ["stock", "etf", "crypto", "commodity"] },
      "enabled": true,
      "sortOrder": 10,
      "memberCount": 5569
    },
    {
      "universe": "bold",
      "label": "BOLD",
      "source": "manual",
      "rule": null,
      "enabled": true,
      "sortOrder": 20,
      "memberCount": 0
    },
    "..."
  ]
}

Query Parameters

The roster is small enough that the defaults return everything in one call; the parameters exist for envelope consistency with the rest of the API.

Response

This endpoint uses the paginated list envelope:

Each universe object:

Membership

source names how a universe’s membership is determined:

• rule — members are selected by a rule over asset attributes, recomputed as the registry changes. bytetrend is every tracked asset of the types in its rule.assetTypes.
• portfolio — members are the holdings of a ByteTree portfolio. Assets join and leave as the portfolio changes.
• manual — a curated list.

Treat source as a string you switch on, not a closed enum — branch on the values you know and fall through gracefully on anything else. rule is populated only for source: "rule".

A memberCount of 0 is a valid state: a universe is listed as soon as it is enabled, and its members follow (see The roster). GET /api/universes/<slug> on an empty universe returns { "universe": "<slug>", "count": 0, "data": {}, "smallOmitted": 0 } — a valid, empty aggregation, not an error. A small universe with members can also come back nearly empty, because group listings omit groups under five assets by default — see Small-group floor.

Errors