> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Budget

> Scopri come i budget aziendali formano un albero di limiti di ACU, come impostare finestre mensili e livelli di utenti per ciascun budget e come gestire i budget tramite l'API.

Con i budget puoi limitare l'utilizzo di ACU rispecchiando la struttura della tua azienda: un limite per l'account, riserve condivise per team o progetti e limiti per utente all'interno di ciascuna riserva.

## Esempi di casi d'uso

### Reparti con amministratori delegati

Acme Corp ha 10 reparti. Ogni responsabile di reparto gestisce i limiti delle proprie organizzazioni, mentre l'IT centrale stabilisce il totale di ciascun reparto. Questo esempio ne mostra due.

Alice, l'amministratrice aziendale, crea un budget per ogni reparto sotto il budget Account e lo condivide con il rispettivo amministratore di reparto. Ogni amministratore di reparto crea poi un budget per ciascuna delle proprie organizzazioni.

![Budget Account di 100,000 ACU con Engineering a 30,000 ACU, che include Payments e Search, e Marketing a 5,000 ACU.](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/budget-departments.svg?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=bfecc16bdf0286471712d39161e2567c)

Budget di reparto sotto il budget Account

* Bob, l'amministratore del reparto Engineering, può impostare limiti e limiti temporanei su qualsiasi budget sotto Engineering. Ad esempio, può assegnare a Payments un limite temporaneo di 6,000 ACU per una settimana particolarmente intensa.
* Bob non può aumentare il limite di 30,000 ACU di Engineering: può farlo solo Alice.
* L'utilizzo di ogni org di Engineering viene conteggiato nel limite di 30,000 ACU, anche se la somma dei budget delle org è superiore.

![Pagina Budget vista da un amministratore di reparto](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/dept-admin-tree.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=cd8d27a58bfeb28446df8597ac4c2dc1)

La pagina Budget vista da un amministratore di reparto, con il budget Account bloccato

![Aumento del limite di un budget figlio](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/dept-admin-edit-child.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=1c1c05e9681f2e62a5b95b344f476a41)

Un amministratore di reparto aumenta il limite di un budget figlio

![Il limite del budget del reparto è in sola lettura](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/dept-admin-own-limit.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=55c58f67119cb0af4c2f17d1db5d1f0a)

Un amministratore di reparto non può modificare il limite del budget del proprio reparto

### Un budget di progetto con limiti per utente più alti

Ogni sviluppatore dispone di 200 ACU al mese. Per l'iniziativa di migrazione, Acme Corp riserva 5,000 ACU e consente a chi lavora al progetto di usarne di più.

Mantieni le organizzazioni Developer tools in un budget Developer tools con un livello predefinito di 200 ACU. Crea un budget Migration initiative con un limite di 5,000 ACU. Inserisci al suo interno l'org del progetto e assegna al budget un livello predefinito di 1,000 ACU. Entrambi i budget si trovano sotto l'Account budget.

![Developer tools a 20,000 ACU con un livello predefinito di 200 ACU e Migration initiative a 5,000 ACU con un livello predefinito di 1,000 ACU.](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/budget-project.svg?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=cb189c909fb5c07095bd6d1f2c406cd6)

Budget Developer tools e Migration initiative con i rispettivi livelli

* Carol, una sviluppatrice che lavora al progetto, può usare fino a 1,000 ACU nell'org Migration e fino a 200 ACU nelle organizzazioni Developer tools.
* L'intero progetto non può mai superare i 5,000 ACU al mese.

![Selettore dei budget in My Analytics](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/my-analytics-multi-budget.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=cf5fd4ca8608b542fec5484fb003985c)

Selettore dei budget in My Analytics con più budget

## Come funzionano i budget

### Albero dei budget

Ogni account Enterprise ha un unico albero dei budget. La radice è l'**Account budget**, sotto cui si trovano i budget figli. Un albero può avere al massimo tre livelli di profondità.

Un budget può contenere una o più organizzazioni. Ogni organizzazione appartiene a un solo budget. Le nuove organizzazioni vengono inserite sotto l'Account budget.

Ad esempio, Acme Corp imposta un limite di 100,000 ACU sul proprio Account budget. Il reparto Engineering suddivide il proprio pool in tre budget figli.

![Account budget di 100,000 ACU con Engineering a 40,000 ACU e i suoi tre budget figli, e Developer tools a 20,000 ACU con tre tier di limiti per utente.](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/budget-tree.svg?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=923ef86ef029390214dbdd478d4f9328)

Albero dei budget con budget e tier di limiti per utente

I tier sono limiti per utente all'interno di un singolo budget, non budget separati.

![Albero dei budget con l'utilizzo di ciascun budget](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/tree.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=70ff5c75cc82a29a77669afc77de160f)

Albero dei budget con l'utilizzo di ciascun budget (dati fittizi)

### Limiti dei budget

Il limite di un budget fissa un tetto all'utilizzo di ACU complessivo delle org del budget e delle org dei suoi budget figli, per una finestra mensile. Un limite `null` indica che non c'è alcun limite.

* **L'utilizzo viene conteggiato per ogni antenato.** L'utilizzo in un budget figlio viene conteggiato anche per il budget padre e per il budget dell'Account.
* **Un antenato esaurito blocca i suoi figli.** Quando un qualsiasi budget lungo il percorso si esaurisce, l'utilizzo in quel ramo si interrompe.
* **La somma dei limiti dei figli può superare il limite del padre.** Il limite del padre resta comunque il tetto del loro utilizzo complessivo.
* **Un budget senza limite è comunque vincolato dai budget padre.**

Un budget collegato a una sola organizzazione condivide il proprio limite con quell'organizzazione. Questo limite può essere impostato anche tramite gli [endpoint deprecati per il limite di ACU organization-level](https://docs.devinenterprise.com/it/admin/billing/org-acu-limits#organization-endpoints). In alternativa, puoi usare l'[endpoint di aggiornamento](#update-a-budget) descritto di seguito.

### Cosa succede quando un budget si esaurisce

Quando un budget si esaurisce, l'utilizzo viene bloccato per le organizzazioni associate. L'utilizzo si blocca anche quando si esaurisce uno qualsiasi dei budget padre. L'utilizzo riprende con la finestra mensile successiva, oppure quando un amministratore aumenta il limite o imposta un limite temporaneo.

* **Sessioni Devin:** non è possibile avviare nuove sessioni e quelle in esecuzione entrano in sospensione. Gli utenti visualizzano il messaggio "Increase your organization's usage limit."
* **Devin CLI e Local Agent di Desktop:** le richieste vengono bloccate. Gli utenti visualizzano il messaggio "Your organization has reached its monthly usage limit. Ask an account admin to raise it, or wait for the limit to reset next month."
* **Devin Review:** le nuove revisioni vengono bloccate.

![Banner del compositore: limite di utilizzo raggiunto](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/cloud-limit-reached.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=b4183e12594ad3d8d84eb223dc6d1246)

Banner del compositore quando il budget è esaurito

### Finestra mensile

I limiti di budget, i limiti per utente e i limiti temporanei vengono reimpostati all'inizio di ogni finestra mensile. Ogni finestra inizia nel giorno di avvio della tua fase di fatturazione, che non sempre coincide con il mese di calendario.

Ad esempio, se la fase di fatturazione inizia il 15, le finestre vanno dal 15 ottobre al 14 novembre, poi dal 15 novembre al 14 dicembre.

Un **limite temporaneo** sostituisce il limite del budget per il resto della finestra attuale. Il limite permanente torna in vigore nella finestra successiva. Un limite personalizzato per utente temporaneo scade alla fine della finestra attuale.

![Budget di Marketing con un limite temporaneo](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/limits-temporary.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=8a19713130eef30fae3153e10400f77d)

Un limite temporaneo porta il budget di Marketing a 6,000 ACU solo per questa finestra

### Limiti utente in un budget

I limiti utente stabiliscono quanto può consumare una singola persona in una finestra mensile. Ogni budget con un'organizzazione collegata ha i propri limiti utente, che si applicano solo all'interno di quel budget.

* **Livelli.** Ogni budget ha i propri livelli e un livello predefinito. Un livello imposta il limite mensile di ACU per i suoi membri.
* **Mappature dei gruppi IdP.** Mappa un gruppo del provider di identità a un livello. I membri del gruppo ottengono quel livello.
* **Eccezioni.** Imposta un limite permanente o temporaneo per un singolo utente.
* **Policy di richiesta.** Ogni livello stabilisce come vengono gestite le richieste di aumento del limite. `unconditional` e `conditional` approvano le richieste fino al `max_limit` del livello. `manual` inoltra le richieste a un amministratore per la revisione.
* **Ambito.** Un limite utente conteggia solo l'utilizzo dell'utente nelle organizzazioni di quel budget.
* **Copia e cancella.** Copia i livelli da un altro budget o dall'account. Puoi anche copiare le mappature dei gruppi IdP, le assegnazioni e le eccezioni. Cancella tutti i livelli di un budget per ricominciare da zero.

> [!WARNING]
>
> Un limite utente su un budget padre non si estende ai budget figli. Ad esempio, se anche Engineering contiene un'org, un limite utente di 300 ACU su Engineering non limita l'utilizzo di un utente in Payments o Search.

![Finestra di dialogo Copia policy di utilizzo](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/copy-policies.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=cc1c5fce8d56e535d8502eab0501729b)

Finestra di dialogo Copia policy di utilizzo con Developer tools come sorgente

### Chi può gestire un budget

Gli amministratori Enterprise gestiscono i budget in **Enterprise Settings**, nella sezione **Budgets**. Gestiscono l'intera gerarchia, compreso l'Account budget.

* **Delega.** Un amministratore Enterprise può condividere un budget con una persona o un gruppo dalla scheda Manage access. Un amministratore delegato può creare budget al suo interno e impostare limiti e limiti temporanei su questi budget figli. La delega va abilitata separatamente: contatta il tuo team di gestione dell'account.
* **Un amministratore delegato non può aumentare il limite del budget che gli è stato condiviso.** Solo un amministratore che gestisce il budget padre può modificarlo.
* **I membri** possono visualizzare il proprio utilizzo e il proprio limite in My Analytics.

![Scheda Manage access del budget Engineering](https://mintcdn.com/cognitionai-enterprise/0zaCf8BmcmvBSHzW/images/admin/budgets/dept-admin-access.png?fit=max\&auto=format\&n=0zaCf8BmcmvBSHzW\&q=85\&s=58dc7d60892a7eba7a56297055dacd8f)

Scheda Manage access del budget Engineering, con Bob come gestore

## Domande frequenti

> [accordion] Gli amministratori dell'organizzazione possono impostare il limite di ACU di un'org?
>
> No. I limiti di ACU delle org vengono impostati dagli amministratori Enterprise. Per consentire a un team di gestire autonomamente i propri limiti, condividi un budget con l'amministratore del team.

> [accordion] Perché l'endpoint del limite dell'org restituisce 409?
>
> Quando i limiti dei budget vengono imposti per la tua azienda, l'endpoint del limite dell'org restituisce HTTP `409` se l'org condivide il proprio budget con altre org oppure se si trova direttamente nel budget Account. Il messaggio di errore è "This organization has no limit of its own. Set the limit on its budget." Ad esempio, se Globex, Initech e Umbrella condividono un unico budget, una richiesta di scrittura del limite per Globex restituisce `409`.

> [accordion] Quando vengono reimpostati i limiti?
>
> All'inizio di ogni finestra mensile. La finestra inizia il giorno di inizio della tua fase di fatturazione.

> [accordion] Un'org può appartenere a due budget?
>
> No. Ogni org appartiene a un solo budget, mentre un budget può contenere più org.

## Gestire i budget con la V3 API

Tutte le richieste si autenticano con un **token utente di servizio** aziendale. Il chiamante deve disporre dell'autorizzazione di account **ManageAcuLimits** oppure di un [accesso delegato](#who-can-manage-a-budget) al budget. Usa `https://api.devin.ai` come URL di base. Consulta la [panoramica della V3 API](https://docs.devinenterprise.com/it/api-reference/v3/overview.md) per indicazioni su autenticazione e utenti di servizio.

Gli endpoint di collezione specifici del budget ricevono il budget nel percorso: `/v3beta1/enterprise/usage-policies/budgets/{budget_id}/...`. Gli endpoint che fanno riferimento a un singolo tier o a una singola richiesta (`/tiers/{tier_id}`, `/requests/{request_id}`) ricavano il budget dal tier o dalla richiesta, quindi condividono i percorsi con gli endpoint a livello di account.

### Semantica di PATCH

Per gli endpoint `PATCH`:

* Un campo omesso rimane invariato.
* Un campo impostato su `null` viene cancellato.
* Un campo impostato su un valore viene creato o aggiornato.

## Endpoint dei budget

### Elencare i budget

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets
```

Restituisce un elenco paginato dei budget dell'account, sia attivi sia archiviati. Ogni budget ha la seguente struttura:

```json theme={null}
{
  "budget_id": "budget-abc123",
  "name": "Engineering",
  "parent_budget_id": "budget-root",
  "org_ids": ["org-xyz789"],
  "status": "active",
  "cycle_acu_limit": 2000,
  "temporary_cycle_acu_limit": null
}
```

* `budget_id`: l'identificatore da usare nei percorsi relativi a un budget.
* `parent_budget_id`: il budget padre; `null` per il budget root dell'account.
* `org_ids`: le organizzazioni collegate a questo budget, il cui utilizzo viene conteggiato su di esso. Vuoto se non è collegata alcuna organizzazione.
* `status`: `active` o `archived`.
* `cycle_acu_limit`: il limite del budget sul consumo di ACU addebitato al budget stesso e ai suoi discendenti in ogni finestra mensile di fatturazione; `null` indica nessun limite.
* `temporary_cycle_acu_limit`: un limite che sostituisce `cycle_acu_limit` fino alla fine del periodo di fatturazione mensile corrente; `null` se non ce n'è nessuno attivo.

### Aggiorna un budget

```http theme={null}
PATCH /v3beta1/enterprise/usage-policies/budgets/{budget_id}
```

Aggiornamento parziale: i campi omessi restano invariati e `null` rimuove un limite. È obbligatorio specificare almeno un campo.

* `parent_budget_id`: sposta il budget, insieme ai suoi sotto-budget, sotto un altro budget attivo. Il budget root non può essere spostato e i budget possono essere annidati al massimo su tre livelli.
* `cycle_acu_limit`, `temporary_cycle_acu_limit`: i limiti del budget, come nella risposta dell'endpoint di elenco.

**Corpo della richiesta — impostare il limite e un aumento temporaneo per il mese corrente**

```json theme={null}
{
  "cycle_acu_limit": 2000,
  "temporary_cycle_acu_limit": 2500
}
```

**Corpo della richiesta — rimozione dei limiti**

```json theme={null}
{
  "cycle_acu_limit": null,
  "temporary_cycle_acu_limit": null
}
```

**Corpo della richiesta — spostare il budget all'interno di un altro budget**

```json theme={null}
{
  "parent_budget_id": "budget-platform"
}
```

Restituisce il budget aggiornato. Se si imposta di nuovo `temporary_cycle_acu_limit`, il limite viene riavviato per la finestra attuale. Per un budget collegato a una sola organizzazione, `cycle_acu_limit` diventa anche il limite di ACU dell'organizzazione.

## Endpoint dei tier

### Elencare i livelli

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/tiers
```

Restituisce un elenco paginato dei livelli del budget in ordine di precedenza: prima quelli con `priority` più alta e, a parità di priorità, prima i più recenti. Ogni tier ha questo formato:

```json theme={null}
{
  "tier_id": "tier-abc123",
  "name": "Engineers",
  "is_default": true,
  "cycle_acu_limit": 500,
  "policy": "manual",
  "max_limit": null,
  "priority": 0,
  "member_count": 42,
  "created_at": 1735689600
}
```

* `is_default`: indica se questo è il tier predefinito del budget.
* `cycle_acu_limit`: il limite di ACU predefinito per ciclo per ciascun membro; `null` indica che non è previsto un limite massimo.
* `policy`: indica come vengono gestite le richieste di aumento del limite relative al tier: `unconditional` e `conditional` le approvano fino a `max_limit`, mentre `manual` richiede la revisione di un amministratore.
* `max_limit`: il limite massimo fino al quale vengono approvate le richieste di aumento; con `null` le richieste vengono approvate senza alcun tetto. È sempre `null` quando `cycle_acu_limit` è `null`.
* `priority`: determina la posizione del tier tra i livelli associati ai gruppi dell'IdP di un utente: prevale il valore più alto e, in caso di parità, il tier creato più di recente. Un'assegnazione esplicita dell'utente ha la precedenza su questo ordinamento, mentre il tier predefinito non rientra mai nell'ordinamento.
* `member_count`: il numero di utenti attualmente assegnati al tier. Per il tier predefinito, include tutti i membri del budget che non appartengono a un altro tier.

### Crea un tier

```http theme={null}
POST /v3beta1/enterprise/usage-policies/budgets/{budget_id}/tiers
```

**Corpo della richiesta**

```json theme={null}
{
  "name": "Engineers",
  "cycle_acu_limit": 500,
  "policy": "manual"
}
```

Il primo tier del budget diventa automaticamente il suo livello predefinito. Restituisce HTTP `201` con il tier creato.

### Recuperare un tier

```http theme={null}
GET /v3beta1/enterprise/usage-policies/tiers/{tier_id}
```

### Aggiorna un tier

```http theme={null}
PATCH /v3beta1/enterprise/usage-policies/tiers/{tier_id}
```

Aggiornamento parziale: i campi omessi restano invariati.

```json theme={null}
{
  "name": "Engineering",
  "cycle_acu_limit": 750
}
```

### Elimina un tier

```http theme={null}
DELETE /v3beta1/enterprise/usage-policies/tiers/{tier_id}
```

Restituisce HTTP `204` in caso di esito positivo. Il livello predefinito non può essere eliminato (prima è necessario promuovere un altro tier a predefinito). Prima di eliminare un tier, occorre spostarne gli eventuali utenti e rimuovere tutte le mappature dei gruppi IdP associate.

## Endpoint per gli utenti del tier

### Elencare gli utenti di un tier

```http theme={null}
GET /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users
```

Restituisce un elenco paginato degli utenti del tier, con i rispettivi limiti determinati. Per il livello predefinito, include tutti i membri del budget che non appartengono a un altro tier:

```json theme={null}
{
  "user_id": "user_abc123",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "cycle_acu_limit_override": null,
  "temporary_cycle_acu_limit": 800,
  "effective_cycle_acu_limit": 800,
  "limit_source": "temporary_override",
  "membership": "explicit"
}
```

* `cycle_acu_limit_override`: la deroga permanente dell'utente, se presente.
* `temporary_cycle_acu_limit`: la sostituzione temporanea dell'utente, presente solo finché è attiva nel periodo di fatturazione mensile corrente.
* `effective_cycle_acu_limit`: il limite attualmente imposto all'utente; `null` indica che è senza limite massimo.
* `limit_source`: l'origine del limite effettivo: `override` (permanente), `temporary_override` o `tier`.
* `membership`: il motivo per cui l'utente appartiene al tier: `explicit` (assegnato direttamente), `idp_group` (tramite la mappatura dei gruppi IdP che ha la precedenza) o `default` (fallback al livello predefinito).

### Assegnare un utente a un tier

```http theme={null}
PUT /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users/{user_id}
```

Idempotente. Restituisce HTTP `204` in caso di esito positivo. Se un utente viene spostato da un altro tier, qualsiasi limite personalizzato per singolo utente viene cancellato: l'utente erediterà quindi inizialmente il limite del tier di destinazione.

### Rimuovere un utente da un tier

```http theme={null}
DELETE /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users/{user_id}
```

Rimuove l'assegnazione esplicita dell'utente a un tier (ed eventuali override). All'utente viene quindi applicato il livello associato a un gruppo dell'IdP, se presente, altrimenti il livello predefinito. In caso di esito positivo, restituisce HTTP `204`.

## Endpoint utente

### Ottenere i limiti di un utente

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/users/{user_id}
```

Restituisce il tier determinato per l'utente, i relativi limiti e l'eventuale richiesta in sospeso nell'ambito del budget. Include i [campi utente del tier](#list-a-tiers-users) descritti sopra, oltre a:

```json theme={null}
{
  "tier_id": "tier-abc123",
  "tier_name": "Engineers",
  "tier_cycle_acu_limit": 500,
  "pending_request_id": null,
  "pending_request_cycle_acu_limit": null
}
```

* `tier_id` / `tier_name`: il tier da cui deriva il limite dell'utente (assegnazione esplicita, mappatura dei gruppi IdP o tier predefinito); `null` se il budget non prevede livelli.
* `tier_cycle_acu_limit`: il limite del tier stesso, prima di qualsiasi override; `null` indica che è senza limite massimo.
* `pending_request_id` / `pending_request_cycle_acu_limit`: l'eventuale richiesta di aumento del limite in sospeso dell'utente e il limite richiesto.

### Imposta o cancella l'override di un utente

```http theme={null}
PATCH /v3beta1/enterprise/usage-policies/budgets/{budget_id}/users/{user_id}
```

User-scoped: l'utente di destinazione deve solo essere membro del budget — non è coinvolto alcun tier e l'assegnazione del tier dell'utente non viene mai modificata.

**Corpo della richiesta — impostare una sostituzione temporanea**

```json theme={null}
{
  "cycle_acu_limit": 800,
  "kind": "temporary"
}
```

`kind` è obbligatorio quando si imposta un valore: `permanent` non scade mai; `temporary` scade alla fine del periodo di fatturazione mensile corrente.

**Corpo della richiesta — cancellare tutte le eccezioni**

```json theme={null}
{
  "cycle_acu_limit": null
}
```

L'endpoint restituisce HTTP `204` in caso di esito positivo.

## Endpoint dei gruppi IdP

Mappa un gruppo IdP a un tier affinché i suoi membri ereditino automaticamente quel tier. Le mappature vengono determinate in tempo reale in base all'appartenenza ai gruppi e non modificano mai l'assegnazione esplicita del tier di un utente: un'assegnazione esplicita ha sempre la precedenza. A un utente che appartiene a più gruppi mappati viene applicato il tier associato con la priorità più alta (ovvero quello con il valore `priority` più alto; a parità di valore prevale il tier più recente).

### Elenco delle mappature dei gruppi IdP

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups
```

Restituisce un elenco paginato delle mappature gruppo-tier del budget, a partire dalla meno recente. Filtra con `?tier_id=` per elencare solo i gruppi mappati a un determinato tier:

```json theme={null}
{
  "idp_group_id": "grp_abc123",
  "idp_group_name": "Engineering",
  "tier_id": "tier-abc123"
}
```

### Ottenere la mappatura di un gruppo IdP

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups/{idp_group_name}
```

Restituisce HTTP `404` se il gruppo non ha alcuna mappatura nel budget.

### Mappa un gruppo IdP a un tier

```http theme={null}
PUT /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups/{idp_group_name}
```

**Corpo della richiesta**

```json theme={null}
{
  "tier_id": "tier-abc123"
}
```

Upsert idempotente. Il tier deve appartenere al budget. Un gruppo può essere mappato al massimo a un tier per budget: se si mappa un gruppo già mappato, questo viene spostato nel tier specificato.

### Rimuovere la mappatura di un gruppo IdP

```http theme={null}
DELETE /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups/{idp_group_name}
```

Restituisce HTTP `204` in caso di esito positivo. Il tier associato non viene più applicato ai membri del gruppo; agli utenti senza un'assegnazione esplicita e senza un altro tier associato si applica il tier predefinito.

## Endpoint per le richieste di aumento del limite

Gli utenti possono richiedere un limite per ciclo più elevato. L'esito dipende dalla `policy` del tier del richiedente: con `unconditional` e `conditional` la richiesta viene approvata automaticamente fino al `max_limit` del tier, mentre con `manual` resta in sospeso finché un amministratore non la esamina tramite questi endpoint.

### Elencare le richieste di aumento del limite

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/requests
```

Restituisce un elenco paginato delle richieste relative al budget, filtrabile con `?status=` (`pending`, `approved`, `denied`, `expired`) e `?user_id=`:

```json theme={null}
{
  "request_id": 42,
  "user_id": "user_abc123",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "tier_id": "tier-abc123",
  "tier_name": "Engineers",
  "current_cycle_acu_limit": 500,
  "requested_cycle_acu_limit": 800,
  "message": "Wrapping up a large migration this month",
  "status": "pending",
  "created_at": 1735689600,
  "reviewed_at": null,
  "reviewer": null
}
```

* `tier_id` / `tier_name`: il tier del richiedente all'interno del budget; `null` se il budget non prevede livelli.
* `current_cycle_acu_limit`: il limite attualmente imposto al richiedente; `null` indica un utilizzo senza limite massimo.
* `status`: `expired` indica che la richiesta era ancora in attesa al termine del relativo ciclo di fatturazione.
* `reviewer`: l'amministratore che ha esaminato la richiesta; `null` finché la richiesta è in attesa.

### Recuperare una richiesta di aumento del limite

```http theme={null}
GET /v3beta1/enterprise/usage-policies/requests/{request_id}
```

### Approvare una richiesta di aumento del limite

```http theme={null}
POST /v3beta1/enterprise/usage-policies/requests/{request_id}/approve
```

Concede il limite richiesto come **sostituzione temporanea**, che scade alla fine del periodo di fatturazione mensile corrente. Facoltativamente, è possibile concedere un limite diverso:

```json theme={null}
{
  "cycle_acu_limit": 700
}
```

Restituisce la richiesta aggiornata. Restituisce HTTP `409` se la richiesta è già stata esaminata o se il richiedente non è più un membro dell'account.

### Rifiutare una richiesta di aumento del limite

```http theme={null}
POST /v3beta1/enterprise/usage-policies/requests/{request_id}/deny
```

Restituisce la richiesta aggiornata oppure HTTP `409` se è già stata esaminata.

## Esempi di flussi di lavoro

### Configurare i tier di un budget

Trova il budget, imposta un limite di 2.000 ACU al mese, quindi crea un tier predefinito in modo che ogni membro del budget disponga di un limite mensile di 500 ACU:

```bash theme={null}
curl "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets" \
  -H "Authorization: Bearer <token>"

curl -X PATCH "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cycle_acu_limit": 2000}'

curl -X POST "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123/tiers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standard", "cycle_acu_limit": 500, "policy": "manual"}'
```

Mappa un gruppo IdP al tier e concedi a un utente un aumento temporaneo per il resto del mese:

```bash theme={null}
curl -X PUT "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123/idp-groups/Engineering" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tier_id": "tier-abc123"}'

curl -X PATCH "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123/users/user_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cycle_acu_limit": 800, "kind": "temporary"}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.