Skip to content
Land Insights Land Insights

Get current-period API usage totals

GET
/api/public/v1/usage/
 
curl --request GET \
  --url https://app-api.landinsights.co/api/public/v1/usage/ \
  --header 'Authorization: Bearer <token>'

Returns the caller’s API token usage for the current billing period: tokens used, tokens included with their tier, any overage and its dollar cost, and the period boundaries. A compact, fixed-size response.

For a per-endpoint / per-day breakdown of where the tokens went, use get_usage_breakdown instead.

Cost: free.

Authorizations

Section titled “Authorizations ”

Responses

Section titled “ Responses ”

200

Section titled “200 ”
Media type application/json
Array<object>

Current-period API token usage totals for the authenticated caller.

When the caller has no active API add-on contract, tier is null and every numeric field is 0.

object
tier
required

The caller’s current API tier (e.g. starter, growth, scale). Null when no API add-on contract is active.

string
nullable
tokens_used
required

Tokens consumed so far in the current billing period.

integer
tokens_included
required

Tokens included with the caller’s tier each billing period.

integer
tokens_overage
required

Tokens used beyond the included allotment — max(0, tokens_used - tokens_included).

integer
overage_amount_cents
required

Cost of the overage tokens so far, in US cents.

integer
period_start
required

Start of the current billing period (ISO 8601). Null when no contract is active.

string format: date-time
nullable
period_end
required

End of the current billing period, when usage counters reset (ISO 8601). Null when no contract is active.

string format: date-time
nullable
Examples
Example StarterTier,Mid-period

Starter tier, mid-period

[
  {
    "tier": "starter",
    "tokens_used": 4120,
    "tokens_included": 30000,
    "tokens_overage": 0,
    "overage_amount_cents": 0,
    "period_start": "2026-06-01T00:00:00Z",
    "period_end": "2026-07-01T00:00:00Z"
  }
]

400

Section titled “400 ”

Validation error.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

401

Section titled “401 ”

Missing or invalid credentials.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

402

Section titled “402 ”

A Pro subscription or higher API tier is required.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

403

Section titled “403 ”

Authenticated but not permitted.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

404

Section titled “404 ”

Resource not found.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

429

Section titled “429 ”

Rate limit exceeded.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

500

Section titled “500 ”

Internal error.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}