# Read current-period usage

- **OpenAPI Version:** `3.2.0`
- **API Version:** `3.1.0`
- **Contact:** Syndai <https://syndai.ai>

## Contents

**Operations**

- [GET /api/v1/external/coding/usage/current-period](#scalar-operation-get-apiv1externalcodingusagecurrent-period)

**Schemas**

- [CurrentPeriodUsageResponse](#scalar-schema-currentperiodusageresponse)
- [AppHostingLine](#scalar-schema-apphostingline)
- [ExtraUsageSummary](#scalar-schema-extrausagesummary)
- [SubscriptionShareLine](#scalar-schema-subscriptionshareline)
- [ProblemDetail](#scalar-schema-problemdetail)
- [ExternalErrorCode](#scalar-schema-externalerrorcode)

<a id="scalar-context-global-servers"></a>

## Servers

- **URL:** `https://api.syndai.ai`

<a id="scalar-context-global-authentication"></a>

## Authentication

- **CustomerApiKey**: HTTP bearer (`API Key`)

  Customer API key sent as a bearer token

## Tags

### Billing

The workspace's plan, balance and prices: read current-period usage, credit packs, plans and the live subscription, and create a payment link for a pack or a first plan. Nothing is charged until a person pays on that link; changing plan, the card and cancelling stay on the Billing page (403 `HUMAN_APPROVAL_REQUIRED`).

## Operations

<a id="scalar-operation-get-apiv1externalcodingusagecurrent-period"></a>

### Read current-period usage

- **Method:** `GET`
- **Path:** `/api/v1/external/coding/usage/current-period`
- **Operation ID:** `getBillingUsage`
- **Tags:** Billing

The workspace's plan and balance for the current monthly period: the included allowance and what is left of it (resets at `included_resets_at`), the prepaid pack balance (`pack_balance_usd`; negative is app-hosting debt), spend this period and the monthly spend cap. Amounts are USD; the portal shows them as credits at `usd_per_credit` from `GET /purchases/tiers`. Needs `coding:billing:read`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`customer_id`**: `string | null`, format: `uuid`

#### Responses

##### 200 Request fulfilled, document follows

**Content type:** `application/json`

[CurrentPeriodUsageResponse](#scalar-schema-currentperiodusageresponse)

<a id="scalar-example-1"></a>

**Generated example:**

```json
{
  "app_hosting": [
    {
      "coding_repository_id": "",
      "publication_id": "",
      "slug": "",
      "translation_usd": 0,
      "usd": 1
    }
  ],
  "autonomous_budget_usd": 1,
  "bids_usd": 0,
  "extra_usage": {
    "accrued_this_month_usd": 1,
    "accrued_this_week_usd": 1,
    "held_usd": 1,
    "month_resets_at": "",
    "monthly_limit_usd": 1,
    "remaining_usd": 1,
    "state": "",
    "week_resets_at": "",
    "weekly_limit_usd": 1
  },
  "hosting_debt_since": "",
  "included_remaining_usd": 1,
  "included_resets_at": "",
  "included_spend_this_period_usd": 1,
  "included_usd": 1,
  "monthly_spend_cap_usd": 1,
  "pack_balance_usd": 1,
  "pack_spend_this_period_usd": 1,
  "period_end": "",
  "period_start": "",
  "plan_code": "",
  "spend_this_period_usd": 1,
  "subscriptions": [
    {
      "share_pct": 1,
      "subject_kind": ""
    }
  ]
}
```

##### 400, 401, 403, 404

- `400` Bad request syntax or unsupported method
- `401` Invalid or missing customer API key
- `403` Insufficient scope or forbidden customer access
- `404` Resource not found

**Content type:** `application/problem+json`

[ProblemDetail](#scalar-schema-problemdetail)

RFC 7807 problem detail returned for public CaaS errors.

<a id="scalar-example-2"></a>

**Generated example:**

```json
{
  "code": "BUDGET_EXHAUSTED",
  "detail": null,
  "existing_run_id": null,
  "instance": null,
  "status": 1,
  "title": "",
  "type": "about:blank",
  "additionalProperty": "anything"
}
```

##### 429 Rate limit exceeded

**Headers:**

- **`Retry-After`**

  Seconds to wait before retrying the request

  `integer`

**Content type:** `application/problem+json`

[ProblemDetail](#scalar-schema-problemdetail)

RFC 7807 problem detail returned for public CaaS errors.

[Generated example](#scalar-example-2)

##### default Unexpected error

**Content type:** `application/problem+json`

[ProblemDetail](#scalar-schema-problemdetail)

<a id="scalar-example-3"></a>

**Generated example:**

```json
null
```

## Schemas

<a id="scalar-schema-currentperiodusageresponse"></a>

### CurrentPeriodUsageResponse

**Type:** `object`

- **`included_remaining_usd` (required)**: `number`
- **`included_resets_at` (required)**: `string`, format: `date-time`
- **`included_spend_this_period_usd` (required)**: `number`
- **`included_usd` (required)**: `number`
- **`monthly_spend_cap_usd` (required)**: `number`
- **`pack_balance_usd` (required)**: `number`
- **`pack_spend_this_period_usd` (required)**: `number`
- **`period_end` (required)**: `string`, format: `date-time`
- **`period_start` (required)**: `string`, format: `date-time`
- **`plan_code` (required)**: `string`
- **`spend_this_period_usd` (required)**: `number`
- **`app_hosting`**: array of [AppHostingLine](#scalar-schema-apphostingline)
- **`autonomous_budget_usd`**: `number | null`
- **`bids_usd`**: `number`, default: `0`
- **`extra_usage`**: [ExtraUsageSummary](#scalar-schema-extrausagesummary) | `null`
- **`hosting_debt_since`**: `string | null`, format: `date-time`
- **`subscriptions`**: array of [SubscriptionShareLine](#scalar-schema-subscriptionshareline)

<a id="scalar-example-4"></a>

**Generated example:**

```json
{
  "app_hosting": [
    {
      "coding_repository_id": "",
      "publication_id": "",
      "slug": "",
      "translation_usd": 0,
      "usd": 1
    }
  ],
  "autonomous_budget_usd": 1,
  "bids_usd": 0,
  "extra_usage": {
    "accrued_this_month_usd": 1,
    "accrued_this_week_usd": 1,
    "held_usd": 1,
    "month_resets_at": "",
    "monthly_limit_usd": 1,
    "remaining_usd": 1,
    "state": "",
    "week_resets_at": "",
    "weekly_limit_usd": 1
  },
  "hosting_debt_since": "",
  "included_remaining_usd": 1,
  "included_resets_at": "",
  "included_spend_this_period_usd": 1,
  "included_usd": 1,
  "monthly_spend_cap_usd": 1,
  "pack_balance_usd": 1,
  "pack_spend_this_period_usd": 1,
  "period_end": "",
  "period_start": "",
  "plan_code": "",
  "spend_this_period_usd": 1,
  "subscriptions": [
    {
      "share_pct": 1,
      "subject_kind": ""
    }
  ]
}
```

<a id="scalar-schema-apphostingline"></a>

### AppHostingLine

**Type:** `object`

- **`coding_repository_id` (required)**: `string`
- **`publication_id` (required)**: `string`
- **`slug` (required)**: `string`
- **`usd` (required)**: `number`
- **`translation_usd`**: `number`, default: `0`

<a id="scalar-example-5"></a>

**Generated example:**

```json
{
  "coding_repository_id": "",
  "publication_id": "",
  "slug": "",
  "translation_usd": 0,
  "usd": 1
}
```

<a id="scalar-schema-extrausagesummary"></a>

### ExtraUsageSummary

**Type:** `object`

- **`accrued_this_month_usd` (required)**: `number`
- **`accrued_this_week_usd` (required)**: `number`
- **`held_usd` (required)**: `number`
- **`month_resets_at` (required)**: `string`, format: `date-time`
- **`monthly_limit_usd` (required)**: `number`
- **`remaining_usd` (required)**: `number`
- **`state` (required)**: `string`
- **`week_resets_at` (required)**: `string`, format: `date-time`
- **`weekly_limit_usd` (required)**: `number`

<a id="scalar-example-6"></a>

**Generated example:**

```json
{
  "accrued_this_month_usd": 1,
  "accrued_this_week_usd": 1,
  "held_usd": 1,
  "month_resets_at": "",
  "monthly_limit_usd": 1,
  "remaining_usd": 1,
  "state": "",
  "week_resets_at": "",
  "weekly_limit_usd": 1
}
```

<a id="scalar-schema-subscriptionshareline"></a>

### SubscriptionShareLine

**Type:** `object`

- **`share_pct` (required)**: `number`
- **`subject_kind` (required)**: `string`

<a id="scalar-example-7"></a>

**Generated example:**

```json
{
  "share_pct": 1,
  "subject_kind": ""
}
```

<a id="scalar-schema-problemdetail"></a>

### ProblemDetail

**Type:** `object`

RFC 7807 problem detail returned for public CaaS errors.

- **`code` (required)**: `string`, possible values: `"BUDGET_EXHAUSTED", "QUOTA_EXCEEDED", "RUN_CONCURRENCY_LIMIT", "CUSTOMER_DISABLED", "REPO_NOT_BOUND", "IDEMPOTENCY_REPLAY", "CONFLICT", "MISSION_BUSY_RETRY", "HITL_REQUEST_CONFLICT", "HITL_REQUEST_SETTLED", "RUN_TERMINATED_BEFORE_RESPONSE", "INVALID_POLICY", "INVALID_SCOPE", "RATE_LIMITED", "INSTALLATION_INCOMPLETE", "SUBSCRIPTION_USAGE_UNAVAILABLE", "INVALID_TOKEN", "ROLE_REQUIRED", "PLAN_UPGRADE_REQUIRED", "EMAIL_MISMATCH", "EXPIRED_TOKEN", "NOT_FOUND", "OVERSCOPE_ACK_REQUIRED", "VERIFY_FAILED", "PUBLISH_IN_FLIGHT", "PUBLISH_UNSUPPORTED_REPO", "PUBLICATION_NOT_LIVE", "NO_APP_DATA", "FEATURE_REQUESTS_NEEDS_MEMBERS", "EMPTY_UPDATE", "BAD_CURSOR", "HUMAN_APPROVAL_REQUIRED", "PROTECTED_PATHS_MANAGED_ONLY", "RUN_IN_FLIGHT", "TEXT_EDIT_REFUSED", "CLI_UPGRADE_REQUIRED", "PRODUCTION_STEP_UP_REQUIRED", "PRICES_UPDATING", "GITHUB_UNAVAILABLE", "PUBLISH_NOT_SET_UP", "PUBLISH_TAG_EXISTS", "PUBLISH_VERSION_EXISTS", "VERSION_NOT_DEPLOYED", "DATA_REFUSED", "INTERNAL_ERROR"`

  Stable error codes surfaced to public CaaS clients.
- **`status` (required)**: `integer`
- **`title` (required)**: `string`
- **`detail`**: `string | null`, default: `null`
- **`existing_run_id`**: `string | null`, default: `null`
- **`instance`**: `string | null`, default: `null`
- **`type`**: `string`, default: `"about:blank"`

<a id="scalar-example-8"></a>

**Generated example:**

```json
{
  "code": "BUDGET_EXHAUSTED",
  "detail": null,
  "existing_run_id": null,
  "instance": null,
  "status": 1,
  "title": "",
  "type": "about:blank",
  "additionalProperty": "anything"
}
```

<a id="scalar-schema-externalerrorcode"></a>

### ExternalErrorCode

**Type:** `string`, possible values: `"BUDGET_EXHAUSTED", "QUOTA_EXCEEDED", "RUN_CONCURRENCY_LIMIT", "CUSTOMER_DISABLED", "REPO_NOT_BOUND", "IDEMPOTENCY_REPLAY", "CONFLICT", "MISSION_BUSY_RETRY", "HITL_REQUEST_CONFLICT", "HITL_REQUEST_SETTLED", "RUN_TERMINATED_BEFORE_RESPONSE", "INVALID_POLICY", "INVALID_SCOPE", "RATE_LIMITED", "INSTALLATION_INCOMPLETE", "SUBSCRIPTION_USAGE_UNAVAILABLE", "INVALID_TOKEN", "ROLE_REQUIRED", "PLAN_UPGRADE_REQUIRED", "EMAIL_MISMATCH", "EXPIRED_TOKEN", "NOT_FOUND", "OVERSCOPE_ACK_REQUIRED", "VERIFY_FAILED", "PUBLISH_IN_FLIGHT", "PUBLISH_UNSUPPORTED_REPO", "PUBLICATION_NOT_LIVE", "NO_APP_DATA", "FEATURE_REQUESTS_NEEDS_MEMBERS", "EMPTY_UPDATE", "BAD_CURSOR", "HUMAN_APPROVAL_REQUIRED", "PROTECTED_PATHS_MANAGED_ONLY", "RUN_IN_FLIGHT", "TEXT_EDIT_REFUSED", "CLI_UPGRADE_REQUIRED", "PRODUCTION_STEP_UP_REQUIRED", "PRICES_UPDATING", "GITHUB_UNAVAILABLE", "PUBLISH_NOT_SET_UP", "PUBLISH_TAG_EXISTS", "PUBLISH_VERSION_EXISTS", "VERSION_NOT_DEPLOYED", "DATA_REFUSED", "INTERNAL_ERROR"`

Stable error codes surfaced to public CaaS clients.