# Apim Throttle Expert

> Diagnose 429 responses from the AI Citadel APIM gateway — identify which rate-limit policy tripped (per-product quota, per-named-value rate-limit-by-key, or backend pool TPM exhaustion).

- **Type:** Skill
- **Install:** `agentstack add skill-aiappsgbb-awesome-gbb-apim-throttle-expert`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aiappsgbb](https://agentstack.voostack.com/s/aiappsgbb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** https://github.com/aiappsgbb/awesome-gbb/tree/main/skills/azure-sre-agent/references/plugins/gbb-citadel/skills/apim_throttle_expert

## Install

```sh
agentstack add skill-aiappsgbb-awesome-gbb-apim-throttle-expert
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# apim_throttle_expert

## When to use

The SRE Agent should invoke this skill when:

- A user reports a 429 from the Citadel gateway
- A scheduled task flags a spike in 429 responses
- Backend pool TPM utilization approaches its limit

## Investigation flow

1. **Identify the failing operation** — ask the user for the path
   (`/llm/v1/chat/completions`, `/doc/analyze`, etc.) and the time window.

2. **Pull APIM diagnostics** from Log Analytics:
   ```kql
   ApiManagementGatewayLogs
   | where TimeGenerated > ago(2h)
   | where ResponseCode == 429
   | summarize count() by OperationId, ClientIpAddress, ProductId, bin(TimeGenerated, 5m)
   | order by TimeGenerated desc
   ```

3. **Classify the 429** by inspecting the response headers in the same log:

   | Header present | Cause | Action |
   |---|---|---|
   | `Retry-After: ` + `x-throttling-source: apim-product-quota` | Per-product monthly quota exhausted | Check product config; consider raising or moving caller to a different product |
   | `Retry-After: ` + `x-throttling-source: rate-limit-by-key` | Per-key rate limit (typically per-spoke MI) | Check rate-limit policy + named value |
   | `Retry-After: ` + `x-aoai-throttle: true` | Backend AOAI TPM exhaustion (not APIM) | Scale up AOAI deployment or move to PTU |
   | No `Retry-After` | Bug in policy — escalate | Read the operation's policy XML |

4. **For backend exhaustion**, check the BackendPool config:
   ```bash
   az apim api operation policy list ...
   ```

5. **Output** the classification, the specific policy / quota that triggered, the per-product utilization, and a recommended action.

## Tools

This skill uses:
- `RunAzCliReadCommands`
- `QueryLogAnalyticsByWorkspaceId`

## Safety

- Never modify APIM policy, named values, or product subscriptions
- Never read APIM subscription key contents
- All actions must be reviewed by a human

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** [aiappsgbb/awesome-gbb](https://github.com/aiappsgbb/awesome-gbb)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aiappsgbb-awesome-gbb-apim-throttle-expert
- Seller: https://agentstack.voostack.com/s/aiappsgbb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.