{
  "openapi": "3.1.0",
  "info": {
    "title": "Usage",
    "version": "2026-10-09",
    "description": "View your team's charges, grouped by day, service, meter, mode, key and rate version. Usage reports are free."
  },
  "servers": [
    {
      "url": "https://api.motor.dev/meta"
    }
  ],
  "security": [
    {
      "SecretKey": []
    }
  ],
  "tags": [
    {
      "name": "Usage"
    }
  ],
  "paths": {
    "/usage": {
      "get": {
        "operationId": "listUsage",
        "tags": [
          "Usage"
        ],
        "summary": "List usage",
        "description": "Lists your team's daily usage for a UTC month, ordered by day. Usage updates until Motor creates the month's invoice. Requires a secret key, which can read usage across all keys on your team for services it has permission to use. Invoice totals may differ from usage totals because each invoice line is rounded to the nearest cent.",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": true,
            "description": "The month in UTC, `YYYY-MM`: the current month or one of the 24 completed months before it.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$"
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "required": false,
            "description": "Filter by service, such as `feature_flags`. The key must be allowed to use it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "meter_id",
            "in": "query",
            "required": false,
            "description": "Filter by meter, such as `feature_flags.evaluations`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Filter by mode, such as `live`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "key_id",
            "in": "query",
            "required": false,
            "description": "Filter by a key on your team, such as `key_BWBeN28Vb7cMEx7Ym8AUzs`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of rows per page: 1 to 200. Defaults to 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `next_cursor` value returned by the previous page. Keep the month and filters the same.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageList"
                },
                "example": {
                  "data": [
                    {
                      "day": "2026-10-05",
                      "service_id": "feature_flags",
                      "meter_id": "feature_flags.evaluations",
                      "mode": "live",
                      "key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs",
                      "rate_version": null,
                      "unit": "evaluation requests",
                      "quantity": 412000,
                      "unit_price_usd": "0.00003",
                      "amount_usd": "12.36"
                    },
                    {
                      "day": "2026-10-05",
                      "service_id": "feature_flags",
                      "meter_id": "feature_flags.metric_events",
                      "mode": "live",
                      "key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs",
                      "rate_version": null,
                      "unit": "metric events",
                      "quantity": 5000,
                      "unit_price_usd": "0.00003",
                      "amount_usd": "0.15"
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, invalid or revoked, or it's a publishable key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "Use a secret key to read usage. Publishable keys can't read it."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The team is suspended (`account_suspended`), or the key cannot access the service specified by `service_id` (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "This key can't use search_index, so it can't read its usage. Update the key's permissions on the API keys page."
                  }
                }
              }
            }
          },
          "404": {
            "description": "`key_id` is unknown or belongs to another team.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "The key doesn't exist."
                  }
                }
              }
            }
          },
          "422": {
            "description": "`month` is missing, or `month`, `limit` or `cursor` is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "error": {
                    "code": "invalid_field",
                    "message": "`month` must be from 2024-10 to 2026-10: the current month and the 24 months before it."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "SecretKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Motor secret key, `motor_sk_...`. Keep it on your server."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "An error. The response has no other data.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "A stable code: `unauthorized`, `account_suspended`, `forbidden`, `not_found` or `invalid_field`."
              },
              "message": {
                "type": "string",
                "description": "What went wrong and what to do, in English."
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "UsageList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageRow"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "The cursor for the next page, or `null` on the last page."
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "additionalProperties": false
      },
      "UsageRow": {
        "type": "object",
        "description": "The usage of one meter by one key on one day, at one price.",
        "properties": {
          "day": {
            "type": "string",
            "format": "date",
            "description": "The day in UTC."
          },
          "service_id": {
            "type": "string",
            "description": "The service, such as `feature_flags`."
          },
          "meter_id": {
            "type": "string",
            "description": "The service's billing meter. Two meters with the same price have separate rows."
          },
          "mode": {
            "type": "string",
            "description": "The usage mode, such as `live`."
          },
          "key_id": {
            "type": "string",
            "description": "The key that Motor charged."
          },
          "rate_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "The version of the published rates used to calculate the charge, or `null` for a service without versioned rates."
          },
          "unit": {
            "type": "string",
            "description": "What `quantity` counts, such as `evaluation requests`."
          },
          "quantity": {
            "type": "integer",
            "minimum": 0,
            "description": "The number of units."
          },
          "unit_price_usd": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{2,12}$",
            "description": "The price per unit in US dollars, returned as an exact decimal string."
          },
          "amount_usd": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{2,12}$",
            "description": "The charge in US dollars, returned as an exact decimal string. Invoices round each line to the nearest cent."
          }
        },
        "required": [
          "day",
          "service_id",
          "meter_id",
          "mode",
          "key_id",
          "rate_version",
          "unit",
          "quantity",
          "unit_price_usd",
          "amount_usd"
        ],
        "additionalProperties": false
      }
    }
  }
}