Backport: feat (provider/gateway): add quota entity id to gateway provider options (#14164)

vercel-ai-sdk[bot] · mclenhard · web-flow · commit 3aca8474e349 · 2026-04-06T12:07:43.000-07:00
This is an automated backport of #14154 to the release-v6.0 branch. FYI @mclenhard Co-authored-by: mat lenhard <mclenhard@gmail.com>
diff --git a/.changeset/quick-meals-help.md b/.changeset/quick-meals-help.md
@@ -0,0 +1,5 @@
+---
+"@ai-sdk/gateway": patch
+---
+
+feat (provider/gateway): add quotaEntityId gateway provider option
diff --git a/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx b/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx
@@ -790,6 +790,10 @@ The following gateway provider options are available:
 
   Restricts routing to models and tools from providers that have signed a BAA with Vercel for the use of AI Gateway (requires Vercel HIPAA BAA add on). BYOK credentials are skipped when `hipaaCompliant` is set to `true` to ensure that requests are only routed to providers that support HIPAA compliance.
 
+- **quotaEntityId** _string_
+
+  The unique identifier for the entity against which quota is tracked. Used for quota management and enforcement purposes.
+
 - **providerTimeouts** _object_
 
   Per-provider timeouts for BYOK credentials in milliseconds. Controls how long to wait for a provider to start responding before falling back to the next available provider.
@@ -898,6 +902,25 @@ const { text } = await generateText({
 });
 ```
 
+#### Quota Entity ID Example
+
+Set `quotaEntityId` to track and enforce quota against a specific entity. This is useful for multi-tenant applications where you need to manage quota at the entity level (e.g., per organization or team).
+
+```ts
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: 'anthropic/claude-sonnet-4.6',
+  prompt: 'Summarize this report...',
+  providerOptions: {
+    gateway: {
+      quotaEntityId: 'org-123',
+    } satisfies GatewayProviderOptions,
+  },
+});
+```
+
 ### Provider-Specific Options
 
 When using provider-specific options through AI Gateway, use the actual provider name (e.g. `anthropic`, `openai`, not `gateway`) as the key:
diff --git a/examples/ai-functions/src/stream-text/gateway-provider-options-quota-entity-id.ts b/examples/ai-functions/src/stream-text/gateway-provider-options-quota-entity-id.ts
@@ -0,0 +1,27 @@
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { streamText } from 'ai';
+import { run } from '../lib/run';
+
+run(async () => {
+  const result = streamText({
+    model: 'openai/gpt-oss-120b',
+    prompt: 'Tell me the history of the tenrec in a few sentences.',
+    providerOptions: {
+      gateway: {
+        quotaEntityId: 'org-123',
+      } satisfies GatewayProviderOptions,
+    },
+  });
+
+  for await (const textPart of result.textStream) {
+    process.stdout.write(textPart);
+  }
+
+  console.log();
+  console.log('Token usage:', await result.usage);
+  console.log('Finish reason:', await result.finishReason);
+  console.log(
+    'Provider metadata:',
+    JSON.stringify(await result.providerMetadata, null, 2),
+  );
+});
diff --git a/packages/gateway/src/gateway-language-model.test.ts b/packages/gateway/src/gateway-language-model.test.ts
@@ -1616,5 +1616,46 @@ describe('GatewayLanguageModel', () => {
         gateway: { zeroDataRetention: true, hipaaCompliant: true },
       });
     });
+
+    it('should pass quotaEntityId option', async () => {
+      prepareJsonResponse({
+        content: { type: 'text', text: 'Test response' },
+      });
+
+      await createTestModel().doGenerate({
+        prompt: TEST_PROMPT,
+        providerOptions: {
+          gateway: {
+            quotaEntityId: 'entity-123',
+          },
+        },
+      });
+
+      const requestBody = await server.calls[0].requestBodyJson;
+      expect(requestBody.providerOptions).toEqual({
+        gateway: { quotaEntityId: 'entity-123' },
+      });
+    });
+
+    it('should pass quotaEntityId with other options', async () => {
+      prepareJsonResponse({
+        content: { type: 'text', text: 'Test response' },
+      });
+
+      await createTestModel().doGenerate({
+        prompt: TEST_PROMPT,
+        providerOptions: {
+          gateway: {
+            quotaEntityId: 'entity-123',
+            user: 'user-456',
+          },
+        },
+      });
+
+      const requestBody = await server.calls[0].requestBodyJson;
+      expect(requestBody.providerOptions).toEqual({
+        gateway: { quotaEntityId: 'entity-123', user: 'user-456' },
+      });
+    });
   });
 });
diff --git a/packages/gateway/src/gateway-provider-options.ts b/packages/gateway/src/gateway-provider-options.ts
@@ -71,6 +71,12 @@ const gatewayProviderOptions = lazySchema(() =>
        * with Vercel AI Gateway for HIPAA compliance will be used.
        */
       hipaaCompliant: z.boolean().optional(),
+      /**
+       * The unique identifier for the entity against which quota is tracked.
+       *
+       * Used for quota management and enforcement purposes.
+       */
+      quotaEntityId: z.string().optional(),
       /**
        * Per-provider timeouts for BYOK credentials in milliseconds.
        * Controls how long to wait for a provider to start responding

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@ai-sdk/gateway": patch
 +---
++
 +feat (provider/gateway): add quotaEntityId gateway provider option