Get started

Usage

What an organization has used, a day at a time, on the Tile API and the Data API. The figures are split by status class as well as by resource, so the volume that counts toward an allowance or an invoice and the availability are read from the same payload. Every operation here needs a session token beside the key.

Retrieve an organization's Tile API usage

GET
/v1/organizations/{organization_id}/usage/tiles

Returns Tile API usage a day at a time, one figure per kind of resource per surface per status class. The split is deliberate: a day on which a resource was served from both the embed and the API, or both succeeded and failed, yields one figure per combination rather than one total, so a reader can add them for a headline number, take the 2xx ones of the api and embedding surfaces, terrain aside, for what the monthly allowance counts, or compare 2xx against 5xx for availability. A request whose caller went away before the server began to answer it, as a map does with the tiles it stops waiting for when it moves, is counted nowhere, however long it had waited. A caller that leaves once its tile has begun does not change how it is counted. A request the server could not finish checking once it knew the organization, its own or the one a share link belongs to, is answered 500 and counted as a 5xx. A combination with usage anywhere in the range carries a figure for every day of it, 0 on the days it had none.

  • A session token minted for api without a user is what authorizes this read, and no member role is checked on top of it; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. The path names the key's own organization: another is a 403, whether or not it exists.
  • Omit start_at and end_at and the range is the current month plus the three complete months before it. A lone start_at runs to the end of the current month, or to a year after it when that comes first, and a lone end_at starts a year before it.
  • A start_at after end_at is a 400, and so is a window of more than 366 calendar days, both ends included, an end_at more than 365 days after start_at, refused at both parameters: ask for a long history a year at a time.
  • A resource_type outside UsageTileResourceType is a 400 naming it.
  • The api surface, the organization's own clients, and the embedding surface, a tile drawn inside the Mountaya-hosted embed, count toward the Tile API's per-minute limit and its monthly allowance, and the allowance counts their figures of class 2xx alone: a tile refused or failed is recorded here and never counted toward it. The other surfaces are recorded so the organization can see them and are never counted: a studio-embedded figure is a tile an Embedded Studio drew, a studio-online figure one Map Studio in Mountaya's web application drew for a member of the organization, and a share figure one drawn through one of the organization's share links. A terrain figure, the base map served through the Tile API, is recorded on whichever surface asked for it and never counted, on any surface.
  • The figures are a series over the window, not a listing of resources, so they are not paged: every figure of the window comes back at once.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Query parameters

start_at

string (date)

in query

First day to report, inclusive, as a UTC calendar day. Omitted together with end_at, the range is the current month plus the three complete months before it. Sent alone, the range runs from it to the end of the current month, or to the day 365 days after it when that comes first. Sent alone, a start_at after the last day of the current month opens no range and is a 400 with one entry, at start_at. A range is at most 366 calendar days, both ends included, so end_at is at most 365 days after start_at. A start_at after end_at is a 400, and so is a wider range, with one entry at start_at and one at end_at.

end_at

string (date)

in query

Last day to report, inclusive, as a UTC calendar day. Sent alone, the range starts on the day 365 days before it, so it spans 366 calendar days, the most a range may. A wider range, an end_at more than 365 days after start_at, is a 400 with one entry at start_at and one at end_at.

used_publishable_key

string

in query

Report only the usage that arrived on one publishable key, named by its pk_ value. It is spelled used_publishable_key rather than publishable_key because the shorter name is how a credential is presented on a query string, and a filter that collided with it would change who the request is authenticated as. The studio-online and share figures are drawn by pages of Mountaya's web application, under a key of its own rather than one of the organization's, so a filter on one of the organization's keys leaves them out.

resource_type

string

in query

One of: itinerary, itineraries, zones, overlay, collection, terrain

Report only one kind of resource. The values follow the tile ROUTES rather than the resources themselves, which is why itinerary and itineraries are both here: the first counts one itinerary's own tiles and the second the aggregate layer covering every itinerary the caller reaches. A request refused, or failed, before any tile route ran, on the products the organization's agreement grants, the key's scope or the rate limit, is recorded under the resource its address names, so each kind reports its refusals beside its traffic; one for the base map under terrain. A request that names no resource, an address no route serves, an identifier that does not parse, or an overlay or a terrain the catalog does not list, is counted nowhere. No Tile API request asks for a payment method, so none is refused for one. A request refused for its key, its session token or its calling page is counted nowhere.

resource_id

string (uuid)

in query

Report only one resource, by its identifier. A terrain figure is recorded under the id the layer catalog gives the terrain its address names, or the elevation raster's own id.

Response 200

Tile API usage a day at a time, one figure per kind of resource per surface per status class.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

array of UsageTilePoint

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s -G https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/usage/tiles \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -d start_at=2026-08-01 \
  -d end_at=2026-08-31 | jq '.data'
200
Response
{
  "data": [
    {
      "date": "2026-08-22",
      "resource_type": "itinerary",
      "surface": "api",
      "status_class": "2xx",
      "requests": 91043
    }
  ]
}

Retrieve an organization's data usage

GET
/v1/organizations/{organization_id}/usage/data

Returns data usage a day at a time, one figure per operation per surface per metric per status class. A combination with usage anywhere in the range carries a figure for every day of it, 0 on the days it had none. requests is recorded for every call that gets past the credential check; the other metrics count the work one kind of call did, so each appears only beside the operation that can emit it. A refused request records requests alone, because the work the other metrics count never happened, and one refused before any operation ran is counted under each operation its document names. UsageDataResourceType says which refusals are counted nowhere. A request whose caller went away before the server began to answer it, by closing its connection or cancelling the request, is counted nowhere, however long it had waited, since its answer reached nobody. A caller that leaves once its answer has begun does not change how it is counted. A request too slow is the server's to fail: one answered 504 because its time budget ran out is counted as a 5xx. So is one the server could not finish checking once it knew the organization, answered 500, on the surface its session token was minted for, and a root field that fails once its operation has run, its answer included, is counted as the failure it was answered with, never as the success its work reached first. A call through Mountaya's MCP server is counted as the same call made to this API directly, its refusals included. One the MCP server could not deliver to this API once it held a session for it, this API unreachable or what stands in front of it answering in its place, is counted as a 5xx on the mcp surface; one it could get no session for names no organization, and is counted nowhere.

  • A session token minted for api without a user is what authorizes this read, and no member role is checked on top of it; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. The path names the key's own organization: another is a 403, whether or not it exists.
  • Omit start_at and end_at and the range is the current month plus the three complete months before it. A lone start_at runs to the end of the current month, or to a year after it when that comes first, and a lone end_at starts a year before it.
  • A start_at after end_at is a 400, and so is a window of more than 366 calendar days, both ends included, an end_at more than 365 days after start_at, refused at both parameters: ask for a long history a year at a time.
  • resource_type and metric may be combined, but only into a pair that exists: polygons belongs to isochrones and nothing else, so asking for it beside directions is a 400 rather than an empty list. A value outside UsageDataResourceType, UsageMetric or UsageDataSurface is a 400 naming its parameter.
  • Usage is recorded under one of four surfaces: api, a request to the Data API from one of the organization's own clients; mcp, a request made through Mountaya's MCP server; studio-embedded, the work an Embedded Studio did for the organization under one of its keys, which is the routing a Map Studio write did (a routed segment, an import preview and confirm, or a zone computed from a source) and every Data API request made with a session token minted for studio-embedded while the organization holds Embedded Studio, such a request being api while it does not; and studio-online, the same work done by Map Studio in Mountaya's web application for a member of the organization. Only api and mcp count toward the Data API's per-minute limit, its monthly allowance and the invoice. The two studio surfaces are reported so the organization can see them, and are never counted. surface keeps one of them; omitted, all four are reported.
  • The figures are a series over the window, not a listing of resources, so they are not paged: every figure of the window comes back at once.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Query parameters

start_at

string (date)

in query

First day to report, inclusive, as a UTC calendar day. Omitted together with end_at, the range is the current month plus the three complete months before it. Sent alone, the range runs from it to the end of the current month, or to the day 365 days after it when that comes first. Sent alone, a start_at after the last day of the current month opens no range and is a 400 with one entry, at start_at. A range is at most 366 calendar days, both ends included, so end_at is at most 365 days after start_at. A start_at after end_at is a 400, and so is a wider range, with one entry at start_at and one at end_at.

end_at

string (date)

in query

Last day to report, inclusive, as a UTC calendar day. Sent alone, the range starts on the day 365 days before it, so it spans 366 calendar days, the most a range may. A wider range, an end_at more than 365 days after start_at, is a 400 with one entry at start_at and one at end_at.

used_publishable_key

string

in query

Report only the usage that arrived on one publishable key, named by its pk_ value. It is spelled used_publishable_key rather than publishable_key because the shorter name is how a credential is presented on a query string, and a filter that collided with it would change who the request is authenticated as. The studio-online and share figures are drawn by pages of Mountaya's web application, under a key of its own rather than one of the organization's, so a filter on one of the organization's keys leaves them out.

resource_type

string

in query

One of: search, geocode, reverse-geocode, pois, directions, suggestions, matrix, isochrones, analyze-geometry, terrain-samples, terrain-profile, terrain-grid, itinerary, export-itinerary

Report only one Data API operation. Combined with metric, the pair must be one that exists; an impossible pair is a 400.

metric

string

in query

One of: requests, results-returned, targets-executed, routes, waypoints, coordinates, elements, polygons, samples

Report only one metric. Combined with resource_type, the pair must be one that exists: polygons belongs to isochrones and nothing else, so asking for it beside directions is a 400.

surface

string

in query

One of: api, mcp, studio-online, studio-embedded

Report only one surface. Omitted, all four are reported. Only api and mcp count toward the per-minute limit, the monthly allowance and the invoice; studio-online and studio-embedded are the work Map Studio in Mountaya's web application and an Embedded Studio did, reported and never counted.

Response 200

Data usage a day at a time, one figure per operation per surface per metric per status class. Only the requests figures of class 2xx on the api and mcp surfaces are what the monthly allowance and the invoice count.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

array of UsageDataPoint

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s -G https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/usage/data \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -d start_at=2026-08-01 \
  -d end_at=2026-08-31 \
  -d resource_type=directions | jq '.data'
200
Response
{
  "data": [
    {
      "date": "2026-08-22",
      "resource_type": "directions",
      "surface": "api",
      "metric": "requests",
      "status_class": "2xx",
      "value": 1284
    }
  ]
}