# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cost Management API v2 Usage API
  version: 1.0.0
extends: openapi/here-usage-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/usage/realms/{realmId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get billable usage for an organization
      effect: read
      questions:
      - How much billable HERE usage did my organization rack up last month?
      - Can I break organization usage down by app or project?
      - Is it possible to filter usage to one billing tag?
      instructions:
      - text: Get billable usage for organization {realmId} from {startDate} to {endDate}.
        slots:
          realmId: path.realmId
          startDate: query.startDate
          endDate: query.endDate
      - text: Show usage for org {realmId} between {startDate} and {endDate} for app {appId}.
        slots:
          realmId: path.realmId
          startDate: query.startDate
          endDate: query.endDate
          appId: query.appId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/usage/realms/{realmId}/csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Export organization usage as CSV
      effect: read
      questions:
      - Can I download my organization's usage as a CSV file for a spreadsheet?
      - Which format options exist for exporting billable usage?
      instructions:
      - text: Export usage for organization {realmId} from {startDate} to {endDate} as CSV.
        slots:
          realmId: path.realmId
          startDate: query.startDate
          endDate: query.endDate
      - text: Give me a CSV of org {realmId} usage for category {category} between {startDate} and {endDate}.
        slots:
          realmId: path.realmId
          category: query.category
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/usage/realms/{realmId}/reports'].get
  update:
    x-apievangelist-phrasing:
      intent: List the status of all usage report requests
      effect: read
      questions:
      - Which usage reports have I requested and are any ready to download?
      - Can I sort my usage report requests by creation date?
      instructions:
      - text: List all usage report requests for organization {realmId}.
        slots:
          realmId: path.realmId
      - text: Show usage report statuses for org {realmId} sorted {sort}.
        slots:
          realmId: path.realmId
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/usage/realms/{realmId}/reports'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a usage report for partner subaccounts
      effect: write
      questions:
      - How do I generate a usage report covering my partner subaccounts?
      - Does the usage report get built immediately or asynchronously?
      instructions:
      - text: Create a usage report for partner org {realmId} and subaccounts {subAccounts} from {startDate} to {endDate}.
        slots:
          realmId: path.realmId
          subAccounts: requestBody.subAccounts
          startDate: query.startDate
          endDate: query.endDate
      - text: Start an async report of subaccount usage {subAccounts} under {realmId} between {startDate} and {endDate}.
        slots:
          subAccounts: requestBody.subAccounts
          realmId: path.realmId
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/usage/realms/{realmId}/reports/{reportId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of one usage report request
      effect: read
      questions:
      - Is the usage report I requested finished yet?
      - Where do I find the download URL for a specific report?
      instructions:
      - text: Check the status of usage report {reportId} for organization {realmId}.
        slots:
          reportId: path.reportId
          realmId: path.realmId
      - text: Check whether report {reportId} in org {realmId} has completed and read its download link from the status.
        slots:
          reportId: path.reportId
          realmId: path.realmId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usage/realms/{realmId}/reports/{reportId}/output'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a completed usage report
      effect: read
      questions:
      - How do I download a finished usage report?
      - What format does the downloaded usage report come in?
      instructions:
      - text: Download usage report {reportId} for organization {realmId}.
        slots:
          reportId: path.reportId
          realmId: path.realmId
      - text: Fetch the gzipped output of report {reportId} from org {realmId}.
        slots:
          reportId: path.reportId
          realmId: path.realmId
      method: generated
      generated: '2026-09-26'