Связаться с намиПопробовать бесплатно

Получить детализацию расходов через API

Статья создана
Обновлена 15 декабря 2025 г.

Примечание

Для работы с API используйте протокол gRPC. Версия REST API в настоящее время не предоставляется.

Yandex Cloud Billing предоставляет публичный API для получения детализации расходов и потребления ресурсов. С его помощью можно получать отчеты за любой период, фильтровать и группировать данные по облакам, каталогам, сервисам, продуктам, ресурсам и меткам, а также автоматизировать сбор данных для интеграции в собственные системы аналитики и мониторинга.

Минимально необходимая роль для получения детализации расходов через API — billing.accounts.viewer. См. описание роли.

Эндпоинт публичного API Yandex Cloud Billing — https://billing.api.cloud.yandex.net.

Сервис ConsumptionCore

Сервис для получения отчетов о потреблении и расходах. Предоставляет методы для получения детализации по различным уровням иерархии.

Чтобы получить детализацию расходов и потребления ресурсов в рамках платежного аккаунта:

Все методы сервиса ConsumptionCore возвращают данные в трехуровневой структуре:

  1. Общие итоги за весь запрошенный период, где:

    • cost — стоимость потребленных ресурсов без учета скидок.
    • credits — примененные скидки (гранты, скидки за объем, резервированное потребление).
    • expense — итоговая стоимость с учетом скидок.

  2. Итоги по сущностям — агрегированные данные для каждой сущности запрошенного типа (облако, каталог, сервис и т. д.).

  3. Временные ряды — разбивка данных по периодам в соответствии с параметром aggregation_period (день, неделя, месяц, квартал, год).

Подробнее см. в справочнике API ConsumptionCore.

Сервис Metadata

Сервис позволяет получить списки облаков, сервисов, продуктов (SKU), меток и ресурсов для последующего использования в запросах детализации. Методы сервиса Metadata возвращают списки доступных сущностей и их атрибутов.

Чтобы получить в рамках платежного аккаунта метаданные о:

  • Доступных облаках, сервисах, продуктах (SKU), ключах меток и диапазонах дат воспользуйтесь вызовом gRPC API Metadata/GetUsage.
  • Доступных ключах и значениях меток воспользуйтесь вызовом gRPC API Metadata/GetLabel.
  • Доступных каталогах для указанных облаков воспользуйтесь вызовом gRPC API Metadata/GetCloud.
  • Всех доступных идентификаторах ресурсов в диапазоне дат воспользуйтесь вызовом gRPC API Metadata/GetResourceIDs.

Подробнее см. в справочнике API Metadata.

Примеры использования

Чтобы воспользоваться примерами, установите утилиту grpcurl и получите данные вашего аккаунта для авторизации.

Получение детализации по платежному аккаунту

Пример запроса для получения отчета по платежному аккаунту за указанный период:

grpcurl -H "authorization: Bearer <IAM-токен>" \
  -d '{
    "billing_account_id": "dn276oa9slgm********",
    "start_date": {
      "seconds": 1704067200
    },
    "end_date": {
      "seconds": 1706745599
    },
    "aggregation_period": "MONTH"
  }' \
  billing.api.cloud.yandex.net:443 \
  yandex.cloud.billing.usage_records.v1.ConsumptionCoreService/GetBillingAccountUsageReport

Где:

  • <IAM-токен> — IAM-токен для аутентификации.
  • billing_account_id — идентификатор платежного аккаунта.
  • start_date — начало периода (включительно).
  • end_date — конец периода (включительно).
  • aggregation_period — период агрегации данных (DAY, WEEK, MONTH, QUARTER, YEAR).
Результат
{
  "currency": "RUB",
  "cost": {
    "value": "15000.50"
  },
  "credit_details": {
    "credit": {
      "value": "-1500.00"
    },
    "monetary_grant_credit": {
      "value": "-1000.00"
    },
    "volume_incentive_credit": {
      "value": "-500.00"
    },
    "cud_credit": {
      "value": "0.00"
    },
    "free_credit": {
      "value": "0.00"
    }
  },
  "expense": {
    "value": "13500.50"
  },
  "entities_data": [
    {
      "cost": {
        "value": "15000.50"
      },
      "credit_details": {
        "credit": {
          "value": "-1500.00"
        },
        "monetary_grant_credit": {
          "value": "-1000.00"
        },
        "volume_incentive_credit": {
          "value": "-500.00"
        },
        "cud_credit": {
          "value": "0.00"
        },
        "free_credit": {
          "value": "0.00"
        }
      },
      "expense": {
        "value": "13500.50"
      },
      "billing_account": {
        "id": "dn276oa9slgm********",
        "name": "My Billing Account"
      },
      "periodic": [
        {
          "cost": {
            "value": "15000.50"
          },
          "credit_details": {
            "credit": {
              "value": "-1500.00"
            },
            "monetary_grant_credit": {
              "value": "-1000.00"
            },
            "volume_incentive_credit": {
              "value": "-500.00"
            },
            "cud_credit": {
              "value": "0.00"
            },
            "free_credit": {
              "value": "0.00"
            }
          },
          "expense": {
            "value": "13500.50"
          },
          "timestamp": "2024-01-01T00:00:00Z"
        }
      ]
    }
  ]
}

Получение детализации по облакам

Пример запроса для получения детализации по конкретным облакам с фильтрацией по сервисам:

grpcurl -H "authorization: Bearer <IAM-токен>" \
  -d '{
    "billing_account_id": "dn276oa9slgm********",
    "start_date": {
      "seconds": 1704067200
    },
    "end_date": {
      "seconds": 1706745599
    },
    "cloud_ids": ["b1gvlrnlw2e6********", "b1gia87mbaom********"],
    "service_ids": ["compute", "storage"],
    "aggregation_period": "MONTH"
  }' \
  billing.api.cloud.yandex.net:443 \
  yandex.cloud.billing.usage_records.v1.ConsumptionCoreService/GetCloudUsageReport

Где:

  • cloud_ids — список идентификаторов облаков для фильтрации.
  • service_ids — список идентификаторов сервисов для фильтрации.

Дополнительные параметры фильтрации:

  • folder_ids — список идентификаторов каталогов.
  • sku_ids — список идентификаторов продуктов (SKU).
  • resource_ids — список идентификаторов ресурсов.
  • labels — фильтрация по меткам ресурсов.
Результат
{
  "currency": "RUB",
  "cost": {
    "value": "8500.25"
  },
  "credit_details": {
    "credit": {
      "value": "-850.00"
    },
    "monetary_grant_credit": {
      "value": "-500.00"
    },
    "volume_incentive_credit": {
      "value": "-350.00"
    },
    "cud_credit": {
      "value": "0.00"
    },
    "free_credit": {
      "value": "0.00"
    }
  },
  "expense": {
    "value": "7650.25"
  },
  "entities_data": [
    {
      "cost": {
        "value": "5000.00"
      },
      "credit_details": {
        "credit": {
          "value": "-500.00"
        },
        "monetary_grant_credit": {
          "value": "-300.00"
        },
        "volume_incentive_credit": {
          "value": "-200.00"
        },
        "cud_credit": {
          "value": "0.00"
        },
        "free_credit": {
          "value": "0.00"
        }
      },
      "expense": {
        "value": "4500.00"
      },
      "cloud": {
        "id": "b1gvlrnlw2e6********",
        "name": "Production Cloud"
      },
      "periodic": [
        {
          "cost": {
            "value": "5000.00"
          },
          "credit_details": {
            "credit": {
              "value": "-500.00"
            },
            "monetary_grant_credit": {
              "value": "-300.00"
            },
            "volume_incentive_credit": {
              "value": "-200.00"
            },
            "cud_credit": {
              "value": "0.00"
            },
            "free_credit": {
              "value": "0.00"
            }
          },
          "expense": {
            "value": "4500.00"
          },
          "timestamp": "2024-01-01T00:00:00Z"
        }
      ]
    },
    {
      "cost": {
        "value": "3500.25"
      },
      "credit_details": {
        "credit": {
          "value": "-350.00"
        },
        "monetary_grant_credit": {
          "value": "-200.00"
        },
        "volume_incentive_credit": {
          "value": "-150.00"
        },
        "cud_credit": {
          "value": "0.00"
        },
        "free_credit": {
          "value": "0.00"
        }
      },
      "expense": {
        "value": "3150.25"
      },
      "cloud": {
        "id": "b1gia87mbaom********",
        "name": "Development Cloud"
      },
      "periodic": [
        {
          "cost": {
            "value": "3500.25"
          },
          "credit_details": {
            "credit": {
              "value": "-350.00"
            },
            "monetary_grant_credit": {
              "value": "-200.00"
            },
            "volume_incentive_credit": {
              "value": "-150.00"
            },
            "cud_credit": {
              "value": "0.00"
            },
            "free_credit": {
              "value": "0.00"
            }
          },
          "expense": {
            "value": "3150.25"
          },
          "timestamp": "2024-01-01T00:00:00Z"
        }
      ]
    }
  ]
}

Получение метаданных

Пример запроса для получения метаданных о доступных облаках, сервисах и продуктах:

grpcurl -H "authorization: Bearer <IAM-токен>" \
  -d '{
    "billing_account_id": "dn276oa9slgm********",
    "start_date": {
      "seconds": 1704067200
    },
    "end_date": {
      "seconds": 1706745599
    }
  }' \
  billing.api.cloud.yandex.net:443 \
  yandex.cloud.billing.usage_records.v1.MetadataService/GetUsage
Результат
{
  "clouds": [
    {
      "id": "b1gvlrnlw2e6********",
      "name": "Production Cloud"
    },
    {
      "id": "b1gia87mbaom********",
      "name": "Development Cloud"
    }
  ],
  "services": [
    {
      "id": "compute",
      "name": "Compute Cloud"
    },
    {
      "id": "storage",
      "name": "Object Storage"
    },
    {
      "id": "vpc",
      "name": "Virtual Private Cloud"
    },
    {
      "id": "managed-kubernetes",
      "name": "Managed Service for Kubernetes"
    }
  ],
  "skus": [
    {
      "id": "sku-compute-vm-standard-v3",
      "name": "Compute VM Standard v3",
      "service_id": "compute"
    },
    {
      "id": "sku-storage-standard",
      "name": "Standard Storage",
      "service_id": "storage"
    },
    {
      "id": "sku-vpc-traffic",
      "name": "VPC Egress Traffic",
      "service_id": "vpc"
    }
  ],
  "label_keys": [
    {
      "key": "environment"
    },
    {
      "key": "project"
    },
    {
      "key": "team"
    }
  ],
  "date_range": {
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-31T23:59:59Z"
  }
}

См. также

Предыдущая
Экспортировать расширенную детализацию
Следующая
Поиск в детализации с помощью Yandex Query