---
title: "Cursor Override OpenAI Base URL: Scope and Fixes When It Fails"
description: "What Cursor's custom API key and Override OpenAI Base URL do and don't cover, why localhost fails, plus a step-by-step debugging order and curl self-checks."
url: https://cdnping.org/en/blog/cursor-override-openai-base-url
language: en
published: 2026-10-23
category: "Developer tools"
tags: ["Cursor","Custom API","Base URL","Troubleshooting","Developer tools"]
source: cdnping.org
license: Free to quote and summarize with a link to the url above.
---
# Cursor Override OpenAI Base URL: Scope and Fixes When It Fails

Cursor's custom API support does less than many tutorials suggest. If you enter an OpenAI API key in settings and turn on Override OpenAI Base URL, it only affects features that call "OpenAI-format models," such as chat and Agent. Tab completion still runs on Cursor's own models. Also, requests go to Cursor's cloud first and are then forwarded from there to the address you entered, so `localhost` and internal addresses will not work. Once you understand these two points, most "I configured it but nothing happens" problems become easy to locate.

Below is a table of what the setting covers, followed by a debugging order. Setting names reflect Cursor's English UI at the time of writing. Cursor updates often and menu locations may change, so if something doesn't match, go by the [official Cursor docs](https://docs.cursor.com) and the settings page in your version.

## What do Cursor's custom API key and Base URL actually control?

On the Models page in Cursor Settings you will usually see several API key fields (OpenAI, Anthropic, Google, and so on). Under the OpenAI group there is an Override OpenAI Base URL toggle. What it means: every model that Cursor calls using the OpenAI API format sends its request to the address you entered, with the key you entered.

A few points are easy to get wrong:

| Question | What actually happens | Impact |
|---|---|---|
| Does it override one model or all of them? | With Override on, it applies to all models that use the OpenAI format, not just the one you added | Model names your endpoint doesn't recognize will return errors |
| Does Tab completion use the custom endpoint? | No. Tab uses Cursor's own completion model | A custom key cannot replace the completion quota in your Cursor subscription |
| Where do requests come from? | From Cursor's servers, not directly from your computer | `localhost`, `127.0.0.1` and `192.168.x.x` do not work; the address must be reachable from the public internet |
| Do all features work with custom models? | Not necessarily. Some features (for example certain Agent capabilities and code apply) depend on Cursor's own models or specific capabilities, so custom models may be unavailable or behave differently | A model that works in Ask but errors in Agent is common |
| Does using your own key still consume Cursor quota? | Requests that go through your custom key are billed to your key; features that are not overridden (such as Tab) still use Cursor's quota | Check your bills in two places |
| Does my code pass through Cursor? | Yes. Even with your own key, prompts are assembled on Cursor's servers and then forwarded | For privacy, read the data policies of both Cursor and the endpoint provider |

If you chose a custom endpoint for data reasons, note that your data passes through two parties, Cursor and the endpoint provider, so read both policies. For how to read a data policy, see [Can third-party AI APIs see your code and conversations?](/en/blog/ai-api-data-privacy-policy)

## Why doesn't the Base URL take effect?

The help requests on the Cursor forum generally come down to these causes:

1. The address is not reachable from the public internet. As noted above, requests are sent by Cursor's servers. Being able to curl it from your own machine does not mean Cursor's servers can reach it. Locally run proxies, company intranet gateways, and domains that only resolve through your local hosts file all fall into this category.
2. The `/v1` path is missing or doubled. Most OpenAI-compatible endpoints expect the Base URL to end at `/v1`, for example `https://api.example.com/v1`, and Cursor appends `/chat/completions` itself. Entering `https://api.example.com` or `https://api.example.com/v1/chat/completions` can both return 404. Follow the endpoint provider's documentation.
3. The API format doesn't match. Override OpenAI Base URL only sends OpenAI-format requests. If the endpoint only supports Anthropic's Messages format, or supports the OpenAI format incompletely (for example no streaming or no `tools` field), you get the pattern where Ask works and Agent errors out.
4. The model name is wrong. The model name you add in Cursor must match the id returned by the endpoint's `/v1/models` exactly, including case and prefix. With Override on, Cursor's other built-in OpenAI model names are also sent to your endpoint, and if it doesn't recognize them it returns errors, so turn off any models you don't use in the list.
5. HTTP/2 problems on the network layer. Some network environments (corporate proxies, certain security software) handle long-lived HTTP/2 connections poorly, which shows up as hanging requests or interrupted streaming. The Network section of Cursor's settings offers an HTTP compatibility mode; switch to HTTP/1.1 and try again. Note that this setting affects the leg from your computer to Cursor's servers, not the leg from Cursor to your endpoint.
6. Key verification failed. When you click Verify, Cursor sends a test request. If verification fails, read the original error message first to find the cause rather than re-entering the key over and over.

## A debugging order you can follow

Follow the steps below and change only one variable at a time.

### Step 1: Confirm Cursor itself is not having problems

When a custom endpoint doesn't work, first rule out a Cursor server outage, since requests must pass through it. Open [Is Cursor down?](/en/down/cursor) to see current reports, or check the Cursor official status page events synced to the [API status page](/en/status). cdnping syncs Cursor's official status page every 15 minutes. According to the records cdnping synced, between 2026-09-17 and 2026-10-17 the Cursor status page had 25 incidents, of which 5 were major and 20 were minor. For example, "Degraded performance and errors across Cursor services," starting at 00:22 UTC on 2026-10-13, lasted about 165 minutes. cdnping's own probing only started on 2026-10-17, so the incident counts here come from the official status page history; the window is just one month and is not a long-term statistic.

If Cursor had incidents during this period, wait for recovery before debugging your own configuration. For how to read incident severity and components, see [How to read the OpenAI and Claude status pages](/en/blog/how-to-read-ai-status-pages); the method applies equally to the Cursor status page. If other AI services were also reporting errors at the same time, compare with [AI service incident roundup: September–October 2026](/en/blog/ai-service-incidents-sep-oct-2026) to judge whether it is a shared upstream problem.

### Step 2: Verify the endpoint with curl from the public internet

Don't test only on your own machine. Ideally run this on a cloud server, or at least from a different network:

```bash
# Replace BASE with the Base URL you entered in Cursor (usually ends in /v1)
BASE="https://api.example.com/v1"
KEY="sk-xxxx"

# 1) List models: confirm the address is reachable, the key is valid, and get the exact model id
curl -sS "$BASE/models" -H "Authorization: Bearer $KEY" | head -c 800; echo

# 2) Non-streaming chat: replace your-model-id with an id returned by the previous step
curl -sS "$BASE/chat/completions" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"your-model-id","messages":[{"role":"user","content":"ping"}]}'

# 3) Streaming chat: Cursor chat uses streaming, so it must be tested separately
curl -sSN "$BASE/chat/completions" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"your-model-id","stream":true,"messages":[{"role":"user","content":"ping"}]}'
```

How to read the results:

- The first command returns an HTML page or 404: the Base URL path is wrong.
- The first works and the second returns model not found: the model name is wrong.
- The second works but the third does not return lines starting with `data:` one at a time: the endpoint does not support streaming, which shows up in Cursor as hanging or errors.
- All three work but Cursor still fails: the problem is in Cursor-side configuration or feature limits; continue to Step 3.

If you also want to look at connection quality, you can use the [online speed test](/en) on the cdnping home page, which measures first connection (including DNS and TLS handshake) and round-trip time to various AI APIs from your browser. However, this measures "your browser to the endpoint," which is not the same path as "Cursor's servers to the endpoint," so treat it as a reference only. For the components of latency, see [AI API latency breakdown: connection setup, gateway round trip, and time to first token](/en/blog/api-latency-connect-rtt-ttft).

### Step 3: Narrow the variables inside Cursor

1. In the Models list, keep only one model id that you have confirmed exists, and turn off the other OpenAI models for now.
2. Click Verify again and note the original error text.
3. Send a simple message in Ask mode first; once that works, try the same prompt in Agent mode.
4. Ask works but Agent errors: most likely the endpoint's support for tools/function calling is incomplete, or the feature itself does not support custom models. For the former, ask the endpoint provider; for the latter, check the Cursor docs.
5. Both modes hang or streaming is interrupted: switch to HTTP compatibility mode (HTTP/1.1) in the Network settings, restart Cursor, and try again.

### Step 4: Confirm the address is genuinely public HTTPS

If your endpoint runs locally or on an internal network, Cursor's servers cannot reach it. This is determined by the architecture and no configuration change will fix it. You need to deploy it at an address with a public domain name and a valid certificate. While you're at it, check that DNS resolution is consistent across different networks and that the certificate chain is complete; at a minimum, opening `https://your-domain/v1/models` in a browser should not produce a certificate warning.

## Debugging checklist

Here is the above condensed into a table to tick off item by item:

| Check | How to confirm | Pass criterion |
|---|---|---|
| Cursor service is healthy | [/en/down/cursor](/en/down/cursor), [/en/status](/en/status) | No ongoing incidents |
| Base URL path | curl `$BASE/models` | Returns a JSON model list |
| Public reachability | Run curl from another machine or network | Same result as on your local machine |
| Model id | Compare with the `/models` response | Exactly matches what you entered in Cursor |
| Streaming support | curl with `"stream":true` | Returns `data:` lines one at a time |
| Other models turned off | Cursor Models list | Only models supported by the endpoint are enabled |
| Verify result | Settings page | No errors |
| Ask / Agent tested separately | Cursor chat panel | At least Ask works |
| HTTP compatibility mode | Network settings | Switch to HTTP/1.1 and retry when streaming stalls |

## What else to look at when choosing an endpoint

Once a custom endpoint is connected to Cursor, all OpenAI-format requests go through it, so when it has problems, Cursor's chat and Agent become unavailable too. Before connecting, check the following:

- Does it return the model you selected? You can run some consistency checks; see [How to confirm which model an API is really giving you](/en/blog/verify-model-authenticity-relay).
- Are availability and billing public and verifiable? For an evaluation method, see [How to choose an AI API relay: 8 checks on availability, billing, and data policy](/en/blog/api-relay-how-to-evaluate).
- Can other tools share it? If you also use Claude Code and Codex, the configuration methods differ; compare with [Configuring custom API endpoints for Claude Code, Codex and OpenCode](/en/blog/configure-custom-api-endpoint-claude-code-codex). For connection errors on the Claude Code side, see [Troubleshooting Claude Code connection timeouts and errors](/en/blog/claude-code-connection-troubleshooting).

As an example, [AGI Plan](https://agiplan.dev) is an aggregation gateway compatible with both OpenAI and Anthropic API formats (AGI Plan is a commercial partner of cdnping). Cursor is one of the tools that lets you enter an endpoint address plus an API key, and connecting works as described above: enter its address as the Base URL and use the model names returned by its `/models`. At `https://agiplan.dev/api/status/requests?month=YYYY-MM` it publishes hourly, per-capability-group counts of successful and failed requests, with no login required, so you can download and check them yourself. The operator also states clearly that it is not an officially authorized channel. Whichever provider you choose, read the terms of service carefully and comply with local regulations and each model provider's usage policy.