Using the GraphAcademy AI proxy in workshops

The Generative AI and GraphRAG workshops we provide on GraphAcademy challenge you to make calls to LLM from your own code. Up until recently, we have provided OpenAI keys as part of the workshop. Now, we have provided a

but you do not need an OpenAI key to run them. Requests go through the GraphAcademy AI proxy instead.

This page is a reference for learners, and for anyone (or any coding agent) working out why a request to the proxy failed.

The GraphAcademy LLM proxy

The proxy is an OpenAI-compatible API hosted on GraphAcademy. You can find it at the following URL:

https://graphacademy.neo4j.com/api/llm/v1

It supports POST /chat/completions (including streaming) and POST /embeddings. Any OpenAI SDK, LangChain, Pydantic AI, or curl works. You change the base URL and the API key and nothing else.

Each key starts with ga- and belongs to one user on one course. On each request, the proxy checks the key, applies the course limits, then forwards the request:

Each course lists the models it allows. Anything else is rejected.

Get a key and configure your project

1. Enrol on the workshop.
2. Open the lesson with the Workshop AI access panel and accept the acceptable-use terms.
3. Copy the API key from the panel into your .env file:

OPENAI_API_KEY="ga-..."
OPENAI_BASE_URL="https://graphacademy.neo4j.com/api/llm/v1"

The keys have been tested on a number of popular frameworks, so you can switch this out for a real key when you are ready to deploy your code.

Limits

Each course sets its own limits. These are the values for the Agent Memory workshop:

Two of these catch people out.

You must keep the lesson open. The proxy only serves a key whose owner has been active on the course in the last 30 minutes. Loading any lesson of the course counts. When the session goes idle, a "Still working?" prompt appears in the lesson. Click I'm still working and the same key starts working again.

Claude models have fewer features. Requests to claude-* models cannot use tools, tool_choice, functions, function_call, or response_format. Use an OpenAI model for tool calling and structured output.

Identical requests are cached for 15 minutes (chat) or 24 hours (embeddings). Streaming responses are never cached. A response with X-Proxy-Cache: HIT costs no tokens.

Common errors

Every error uses the OpenAI error shape:

{
  "error": {
    "message": "Your workshop AI session has gone idle. ...",
    "type": "permission_error",
    "code": "inactive"
  }
}

Match on code, which is stable, rather than on message.

Errors from the upstream provider are passed through with the provider's own status code. A 502 with upstream_error means the proxy could not reach the provider. Retry after a short wait.

If a request still fails

Work through this list in order. It follows the order the proxy checks each request, so the first item that fails is the cause.

1. OPENAI_API_KEY starts with ga- and OPENAI_BASE_URL ends with /api/llm/v1.
2. You are enrolled on the course the key was issued for.
3. The key has not passed its access window.
4. You have loaded a lesson of the course in the last 30 minutes.
5. The model is on the course's allowed list.
6. You are under the call rate limit.
7. You have tokens left in the budget.

If all of these hold and you still get an error, include the code and HTTP status when you ask for help.