Hippomundo Enterprise

Compatibility policy · Changelog

Returns the authenticated customer's available balance, spend in the current UTC calendar month and daily activity for the most recent 30 UTC calendar dates by endpoint. Balance and spend are authoritative financial figures. Recent activity is operational reporting that is updated once an hour, so it can lag by up to an hour; it never changes a charge. This endpoint is free (0 credits) and rate-limited.

Parameters

Field Type Description

Field	Type	Description
`X-Hippomundo-Freshness`	header · string	Requests fresher data for this call. `live` bypasses the freshness cache; the override may only request fresher data and never affects price. Any other value fails validation. Allowed values: `["cached","live"]`.
`Hippomundo-Version`	header · string	Optional pin to the API version your integration was built against. The only accepted value is `v1`, which today changes nothing. If a later version of the API changes behaviour in a way that is not backwards compatible, requests that send `v1` keep the v1 behaviour. Any other value returns `400 unsupported_version`.

X-Hippomundo-Freshness

header · string

Requests fresher data for this call. live bypasses the freshness cache; the override may only request fresher data and never affects price. Any other value fails validation.

Allowed values: ["cached","live"].

Hippomundo-Version

header · string

Optional pin to the API version your integration was built against. The only accepted value is v1, which today changes nothing. If a later version of the API changes behaviour in a way that is not backwards compatible, requests that send v1 keep the v1 behaviour. Any other value returns 400 unsupported_version.

Response 200 · application/json

Current balance, period spend and recent activity.

Field	Type	Description
`Body`	Usage	Current financial usage summary plus recent operational activity, ordered newest date first and then by endpoint. The current reporting period is the UTC calendar month; recent activity covers the most recent 30 UTC calendar dates, including today. Additional properties: `false`.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: X-RateLimit-Limit`	integer	Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses.
`Header: X-RateLimit-Remaining`	integer	Requests remaining in the applied rate-limit window.

Related schemas: Usage

Example

{
  "balance_milli_credits": 187500,
  "current_period": {
    "ends_at": "2026-09-01T00:00:00Z",
    "spent_milli_credits": 12500,
    "starts_at": "2026-08-01T00:00:00Z"
  },
  "recent_activity": [
    {
      "charged_milli_credits": 7000,
      "date": "2026-08-23",
      "denied_requests": 1,
      "endpoint": "searchHorses",
      "successful_requests": 7
    }
  ]
}

Response 400 · application/problem+json

400 — one of the registered codes malformed_request, invalid_page_token, page_token_expired or unsupported_version; branch on the body code. Not retryable without changing the request. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Page token is malformed or mismatched

{
  "charged": false,
  "code": "invalid_page_token",
  "detail": "The supplied page token is not valid for this query and API key.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000001",
  "request_id": "01J5AR8Q2K0000000000000001",
  "retryable": false,
  "status": 400,
  "title": "Invalid page token",
  "type": "https://enterprise.hippomundo.com/docs/errors/invalid_page_token"
}

Request syntax cannot be parsed

{
  "charged": false,
  "code": "malformed_request",
  "detail": "The request could not be parsed.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000000",
  "request_id": "01J5AR8Q2K0000000000000000",
  "retryable": false,
  "status": 400,
  "title": "Malformed request",
  "type": "https://enterprise.hippomundo.com/docs/errors/malformed_request"
}

Page token past its public expiry

{
  "charged": false,
  "code": "page_token_expired",
  "detail": "The traversal token has expired; restart from page one.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000002",
  "request_id": "01J5AR8Q2K0000000000000002",
  "retryable": false,
  "status": 400,
  "title": "Page token expired",
  "type": "https://enterprise.hippomundo.com/docs/errors/page_token_expired"
}

Hippomundo-Version is not supported

{
  "charged": false,
  "code": "unsupported_version",
  "detail": "The requested API version is not supported.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000003",
  "request_id": "01J5AR8Q2K0000000000000003",
  "retryable": false,
  "status": 400,
  "title": "Unsupported version",
  "type": "https://enterprise.hippomundo.com/docs/errors/unsupported_version"
}

Response 401 · application/problem+json

401 invalid_api_key — the API key is missing, invalid, revoked or otherwise unusable; the states are deliberately indistinguishable. Not retryable without different credentials. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: WWW-Authenticate`	string · required	Always `ApiKey`, without credential detail.

Related schemas: Problem

API key missing, invalid, revoked or otherwise unusable

{
  "charged": false,
  "code": "invalid_api_key",
  "detail": "The request was not authenticated.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000004",
  "request_id": "01J5AR8Q2K0000000000000004",
  "retryable": false,
  "status": 401,
  "title": "Invalid API key",
  "type": "https://enterprise.hippomundo.com/docs/errors/invalid_api_key"
}

Response 403 · application/problem+json

403 endpoint_not_entitled — the authenticated Customer lacks a required entitlement for a discoverable public endpoint it has not purchased. Private endpoints never return 403; they return 404 not_found. Not retryable without purchasing the entitlement. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Public endpoint not purchased

{
  "charged": false,
  "code": "endpoint_not_entitled",
  "detail": "The account is not entitled to this endpoint.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000007",
  "request_id": "01J5AR8Q2K0000000000000007",
  "retryable": false,
  "status": 403,
  "title": "Endpoint not entitled",
  "type": "https://enterprise.hippomundo.com/docs/errors/endpoint_not_entitled"
}

Response 406 · application/problem+json

406 not_acceptable — the Accept header excludes application/json, the media type of every successful response. Omit the header or send one that admits application/json, for example application/json, application/* or */*. Error responses are always application/problem+json. Not retryable without changing the Accept header. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Requested response media type unsupported

{
  "charged": false,
  "code": "not_acceptable",
  "detail": "The requested response media type is not supported.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000A",
  "request_id": "01J5AR8Q2K000000000000000A",
  "retryable": false,
  "status": 406,
  "title": "Not acceptable",
  "type": "https://enterprise.hippomundo.com/docs/errors/not_acceptable"
}

Response 422 · application/problem+json

422 validation_failed — parsed public inputs fail the documented schema or combination rules. errors lists up to 20 field-level items in request-field order, without messages or rejected values; errors_truncated may be true when more exist. Not retryable without correcting the request. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Parsed public inputs fail the documented rules

{
  "charged": false,
  "code": "validation_failed",
  "detail": "One or more request parameters are invalid.",
  "errors": [
    {
      "code": "invalid_format",
      "field": "date_from",
      "location": "query"
    }
  ],
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000E",
  "request_id": "01J5AR8Q2K000000000000000E",
  "retryable": false,
  "status": 422,
  "title": "Request validation failed",
  "type": "https://enterprise.hippomundo.com/docs/errors/validation_failed"
}

Response 429 · application/problem+json

429 rate_limit_exceeded — the Customer or key rate policy rejected the request. Retryable after waiting at least Retry-After; preserve the same idempotency key for a billable retry. Carries the same rate-limit headers used on successful authenticated responses. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: Retry-After`	integer	Seconds to wait before retrying. Required on `429` and on `402 api_key_credit_cap_reached`, where it counts to the start of the next UTC day or month; present on `503` when the service knows a meaningful recovery interval. Minimum: `0`.
`Header: X-RateLimit-Limit`	integer	Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses.
`Header: X-RateLimit-Remaining`	integer	Requests remaining in the applied rate-limit window.

Related schemas: Problem

Rate policy rejected the request

{
  "charged": false,
  "code": "rate_limit_exceeded",
  "detail": "The rate limit for this API key was exceeded.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000F",
  "request_id": "01J5AR8Q2K000000000000000F",
  "retryable": true,
  "status": 429,
  "title": "Rate limit exceeded",
  "type": "https://enterprise.hippomundo.com/docs/errors/rate_limit_exceeded"
}

Response 500 · application/problem+json

500 internal_error — an unexpected Hippomundo failure with no safer public classification. Retryability is occurrence-specific; honor the body retryable field, use exponential backoff with jitter, preserve the idempotency key and report persistent failures with the request_id. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Unexpected failure with no safer classification

{
  "charged": false,
  "code": "internal_error",
  "detail": "An unexpected internal error occurred.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000G",
  "request_id": "01J5AR8Q2K000000000000000G",
  "retryable": false,
  "status": 500,
  "title": "Internal error",
  "type": "https://enterprise.hippomundo.com/docs/errors/internal_error"
}

Response 503 · application/problem+json

503 service_unavailable — the service or a required ledger or dependency is temporarily unavailable. Retryable; honor Retry-After when present and use exponential backoff with jitter. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: Retry-After`	integer	Seconds to wait before retrying. Required on `429` and on `402 api_key_credit_cap_reached`, where it counts to the start of the next UTC day or month; present on `503` when the service knows a meaningful recovery interval. Minimum: `0`.

Related schemas: Problem

Service temporarily unavailable

{
  "charged": false,
  "code": "service_unavailable",
  "detail": "The service is temporarily unavailable.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000J",
  "request_id": "01J5AR8Q2K000000000000000J",
  "retryable": true,
  "status": 503,
  "title": "Service unavailable",
  "type": "https://enterprise.hippomundo.com/docs/errors/service_unavailable"
}

OpenAPI definition

Related schemas: Usage

Complete OpenAPI definition

{
  "description": "Returns the authenticated customer's available balance, spend in the\ncurrent UTC calendar month and daily activity for the most recent 30\nUTC calendar dates by endpoint.\nBalance and spend are authoritative financial figures. Recent activity\nis operational reporting that is updated once an hour, so it can lag\nby up to an hour; it never changes a charge. This endpoint is free\n(0 credits) and rate-limited.\n",
  "operationId": "getUsage",
  "parameters": [
    {
      "$ref": "#/components/parameters/FreshnessOverride"
    },
    {
      "$ref": "#/components/parameters/VersionHeader"
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "example": {
            "balance_milli_credits": 187500,
            "current_period": {
              "ends_at": "2026-09-01T00:00:00Z",
              "spent_milli_credits": 12500,
              "starts_at": "2026-08-01T00:00:00Z"
            },
            "recent_activity": [
              {
                "charged_milli_credits": 7000,
                "date": "2026-08-23",
                "denied_requests": 1,
                "endpoint": "searchHorses",
                "successful_requests": 7
              }
            ]
          },
          "schema": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "description": "Current balance, period spend and recent activity.",
      "headers": {
        "Hippomundo-Request-ID": {
          "$ref": "#/components/headers/HippomundoRequestId"
        },
        "X-RateLimit-Limit": {
          "$ref": "#/components/headers/RateLimitLimit"
        },
        "X-RateLimit-Remaining": {
          "$ref": "#/components/headers/RateLimitRemaining"
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "403": {
      "$ref": "#/components/responses/EndpointNotEntitled"
    },
    "406": {
      "$ref": "#/components/responses/NotAcceptable"
    },
    "422": {
      "$ref": "#/components/responses/ValidationFailed"
    },
    "429": {
      "$ref": "#/components/responses/RateLimitExceeded"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    },
    "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
    }
  },
  "summary": "Get current usage",
  "tags": [
    "account"
  ]
}