# GET /usage (/api-reference/endpoints/usage/get)

Returns the team's plan, limits and usage in the current period.

MepMail API operation. Base URL https://api.mepmail.dev (self-hosted: the instance's own API origin); authenticate with `Authorization: Bearer ms_...`. The wire format is Resend-compatible. Full OpenAPI 3.1 spec: /openapi.json.

```json
{
  "responses": {
    "200": {
      "description": "Effective plan and usage limits. Annual Send contracts renew their 110K allowance monthly within the paid year; overage is disabled and its numeric rate is zero. MepMail extension; plan, limits and period are null on self-hosted and system teams.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "object": {
                "type": "string",
                "enum": [
                  "usage"
                ]
              },
              "cloud": {
                "type": "boolean",
                "description": "True on MepMail Cloud, where plan limits apply"
              },
              "plan": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "free",
                  "starter",
                  "pro",
                  "scale",
                  null
                ],
                "description": "Effective plan; null self-hosted or on the instance's own (system) team"
              },
              "limits": {
                "type": "object",
                "properties": {
                  "emails_per_day": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Daily cap (UTC day) on Free and Starter; null on monthly plans and self-hosted"
                  },
                  "emails_per_month": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Emails included per billing period on Pro and Scale; null on daily plans and self-hosted"
                  },
                  "domains": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "null = unlimited or self-hosted"
                  },
                  "contacts": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Contacts the team may hold; null = unlimited or self-hosted"
                  }
                },
                "required": [
                  "emails_per_day",
                  "emails_per_month",
                  "domains",
                  "contacts"
                ]
              },
              "today": {
                "type": "object",
                "properties": {
                  "emails_sent": {
                    "type": "integer",
                    "description": "Emails accepted so far this UTC day"
                  },
                  "resets_at": {
                    "type": "string",
                    "description": "Next UTC midnight, when the daily counter resets"
                  }
                },
                "required": [
                  "emails_sent",
                  "resets_at"
                ]
              },
              "period": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "emails_sent": {
                    "type": "integer",
                    "description": "Emails accepted so far this billing period"
                  },
                  "included": {
                    "type": "integer",
                    "description": "Emails the plan includes per period"
                  },
                  "overage_enabled": {
                    "type": "boolean",
                    "description": "Whether sends past `included` bill overage instead of being refused"
                  },
                  "overage_usd_per_1k": {
                    "type": "number",
                    "description": "Overage price per 1,000 emails, in USD"
                  },
                  "starts_at": {
                    "type": "string",
                    "description": "Billing period start"
                  },
                  "ends_at": {
                    "type": "string",
                    "description": "Billing period end, when the counter resets"
                  }
                },
                "required": [
                  "emails_sent",
                  "included",
                  "overage_enabled",
                  "overage_usd_per_1k",
                  "starts_at",
                  "ends_at"
                ],
                "description": "Billing-period usage on monthly plans; null on daily plans and self-hosted"
              },
              "team": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              },
              "app_url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Dashboard origin, for building links; null when unset"
              }
            },
            "required": [
              "object",
              "cloud",
              "plan",
              "limits",
              "today",
              "period",
              "team",
              "app_url"
            ]
          },
          "example": {
            "object": "usage",
            "cloud": false,
            "plan": "free",
            "limits": {
              "emails_per_day": 1,
              "emails_per_month": 1,
              "domains": 1,
              "contacts": 1
            },
            "today": {
              "emails_sent": 1,
              "resets_at": "2026-10-19T12:00:00.000Z"
            },
            "period": {
              "emails_sent": 1,
              "included": 1,
              "overage_enabled": false,
              "overage_usd_per_1k": 1,
              "starts_at": "2026-10-19T12:00:00.000Z",
              "ends_at": "2026-10-19T12:00:00.000Z"
            },
            "team": {
              "id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb",
              "name": "Order updates"
            },
            "app_url": "app url"
          }
        }
      }
    },
    "401": {
      "description": "Missing, malformed or invalid API key",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "statusCode": {
                "type": "number"
              },
              "name": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "statusCode",
              "name",
              "message"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Restricted API key",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "statusCode": {
                "type": "number"
              },
              "name": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "statusCode",
              "name",
              "message"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Contract terms or bindings unavailable. Counters remain under usage; period is null when no monthly allowance is verified. No estimated or null overage rate is returned.",
      "content": {
        "application/json": {
          "schema": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "statusCode": {
                    "type": "number"
                  },
                  "name": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                },
                "required": [
                  "statusCode",
                  "name",
                  "message"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "usage": {
                    "type": "object",
                    "properties": {
                      "today": {
                        "type": "object",
                        "properties": {
                          "emails_sent": {
                            "type": "integer",
                            "description": "Emails accepted so far this UTC day"
                          },
                          "resets_at": {
                            "type": "string",
                            "description": "Next UTC midnight, when the daily counter resets"
                          }
                        },
                        "required": [
                          "emails_sent",
                          "resets_at"
                        ]
                      },
                      "period": {
                        "type": [
                          "object",
                          "null"
                        ],
                        "properties": {
                          "emails_sent": {
                            "type": "integer"
                          },
                          "included": {
                            "type": "integer"
                          },
                          "overage_enabled": {
                            "type": "boolean"
                          },
                          "starts_at": {
                            "type": "string"
                          },
                          "ends_at": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "emails_sent",
                          "included",
                          "overage_enabled",
                          "starts_at",
                          "ends_at"
                        ]
                      }
                    },
                    "required": [
                      "today",
                      "period"
                    ]
                  }
                },
                "required": [
                  "usage"
                ]
              }
            ]
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After",
      "headers": {
        "Retry-After": {
          "description": "Seconds to wait before retrying.",
          "schema": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "statusCode": {
                "type": "number"
              },
              "name": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "statusCode",
              "name",
              "message"
            ]
          }
        }
      }
    }
  },
  "operationId": "getUsage",
  "summary": "Get plan and usage",
  "tags": [
    "Account"
  ],
  "description": "Returns the team's plan, limits and usage in the current period."
}
```