--- title: "List PAYG retail rates for a market" method: GET path: "/v1/rates" tags: ["Rates"] --- # List PAYG retail rates for a market `GET /v1/rates` ## Request - Base URL: `https://api.telgea.com` - URL: `https://api.telgea.com/v1/rates` - Auth: API key in header `x-api-key` Retrieves the pay-as-you-go retail price list for a market — international calling and messaging per destination, or roaming data per visited country. Pass a `market` (an ISO 3166-1 alpha-2 country code — the home-plan market) and a rate `type`. The provider that prices the market is resolved internally, so the response is provider-agnostic: it carries only the country, the per-unit price, its unit, the currency and when it took effect. Prices are your organization's: any rate negotiated for it replaces the list price. They are in the provider's native currency; convert as needed. Calling and messaging are priced from the country the subscriber is in. That is the market by default — a subscriber at home. Add `servingCountry` to price the same market's plan while roaming: `market=DE&servingCountry=DK` is a German plan used in Denmark, and the response echoes the `servingCountry` it priced from. `ROAMING_DATA` has no single serving country — it returns a per-MB price for every visited country — so it ignores the parameter and answers with `servingCountry: null`. Calls and messages are priced outbound by default — what the subscriber pays to reach each destination. Add `direction=inbound` for the other leg: what the subscriber pays when someone in each country reaches them, which is chargeable while roaming. The response echoes the `direction` it priced; `ROAMING_DATA` has none and answers with `direction: null`. Every country is listed, and a country that costs the subscriber nothing carries `ratePerUnit: 0` rather than being left out. That covers both a route priced free — calls inside the EU/EEA, under roam-like-at-home — and one we publish no pay-as-you-go price for, such as a roaming-data country included in the plan. For calling and messaging the serving country itself is not listed, since a call that stays inside it is not an international one. Prices are those in effect today. Add `asOfDate` (YYYY-MM-DD) to read the list for another day — for instance, a price change scheduled to take effect next month. The response echoes the `asOfDate` it priced. The provider is always the one serving the market today. A market no provider serves answers `403` `COUNTRY_NOT_SUPPORTED`. **Scope:** `rates:read`. ## Query parameters - `market` string, required: The home-plan market to price, as an ISO 3166-1 alpha-2 country code. The provider is resolved internally. - `type` 'INTL_VOICE' | 'INTL_SMS' | 'INTL_MMS' | 'ROAMING_DATA', required: The rate type to price: INTL_VOICE (per minute), INTL_SMS / INTL_MMS (per message), or ROAMING_DATA (per MB) - `servingCountry` string: The country the subscriber is calling from, when it differs from the market (roaming). Defaults to the market, which prices calls placed at home. Ignored for ROAMING_DATA, which prices every visited country in one list. - `direction` 'outbound' | 'inbound': Which leg of a call or message to price: outbound — the subscriber calls or texts the destination — or inbound — someone in that country reaches the subscriber, which is chargeable while roaming. Defaults to outbound. Ignored for ROAMING_DATA. - `asOfDate` string, date: The day to price (YYYY-MM-DD): the rates in effect then. Defaults to today, so a price scheduled to take effect later is never quoted early. The provider is the one serving the market today. ## Response `200` Successfully retrieved the retail rates for the market. - RatesResponse - `market` string, required: The market that was priced. - `servingCountry` string, nullable, required: The country the calls were priced from — the requested one, or the market when none was sent. Null for ROAMING_DATA, which prices each visited country in `rates`. - `direction` 'outbound' | 'inbound' | 'null', nullable, required: The direction the list was priced for — the requested one, or outbound when none was sent. Null for ROAMING_DATA, which has no direction. - `asOfDate` string, date, required: The day the list was priced for — the requested one, or today when none was sent. - `rates` Rate[], required: One entry per country — every destination but the serving country for calling, every visited country for data. A country that costs nothing is listed at 0. - `country` string, required: ISO 3166-1 alpha-2 country the price applies to — the destination for calling/SMS, the visited country for data. - `ratePerUnit` number, required: Price per unit in `currency`, to six decimal places. `0` means the country costs nothing — either a route priced free (calls inside the EU/EEA, under roam-like-at-home) or one we publish no pay-as-you-go price for, such as a roaming-data country included in the plan. - `unit` string, required: minutes (voice), count (SMS/MMS), or mb (data). Set even when the country costs nothing. - `currency` string, nullable, required: The market's ISO 4217 currency — the provider's native one, the same for every country in the list. Null only when nothing in the market is priced, leaving no currency to quote. - `validFrom` string, nullable, required: When this rate took effect (ISO-8601), or null if unknown. ## Other responses - `400`: Request failed schema validation, or was refused by a business rule - `401`: Missing or invalid API key in the X-API-Key header - `403`: The API key lacks the rates:read scope, or no provider serves the requested market - `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets. - `500`: Internal server error. Contact support if this persists. --- [API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)