# Docs

- Guides

  - **Get started**
  - [Overview](/docs): ACS Infra serves Base models for research. Find where to start, and which pages to read for what you need.
  - [Quickstart](/docs/quickstart): Send one prompt to a Base model with curl and with OpenAI's Python SDK, read the tokens it writes with their log probabilities, and stream them.
  - [Get access](/docs/get-access): Apply for access, set your password, sign in to the App, and get back in when you forget your password or your access is suspended.
  - [Use API keys](/docs/api-keys): Make an API key in the App, send it with each request, and rename, pause, or revoke it when a script no longer needs it.

  - **Use the API**
  - [Sample continuations](/docs/sampling): Choose how a Base model samples, send several prompts in one request, stream a Completion, and repeat a sample.
  - [Read token probabilities](/docs/token-probabilities): Get the log probabilities of the generated tokens, of the prompt's tokens, and of the whole vocabulary, and return the prompt with the Completion.
  - [Read Activations](/docs/activations): Read the residual stream of a Base model at the Layers you choose, decode it, and check it before you use it.
  - [Steer a Completion](/docs/steering): Add Steering vectors to the residual stream of a Base model to change what it writes, and read the steered Layers in the same request.
  - [Run a Job](/docs/jobs): Submit one Completion request as a Job, read its status, fetch its result with the status it ended with, or cancel it.
  - [Harvest Activations](/docs/harvest): Read the residual stream of many prompts in the background, then download it as safetensors files and read them in Python.
  - [Grow a Loom with the API](/docs/loom): Grow a tree of Completions from one prompt through the API, follow each Branch as it runs, and change, export, or import the tree.
  - [Retry requests safely](/docs/retries): Send a request again without paying twice, know which errors to try again, and set the client for long requests.

  - **Use the App**
  - [Use the App](/docs/app): Find each page of the App after you sign in, read the tokens that you used and have left, and send feedback to the team.
  - [Use the Playground](/docs/app/playground): Run Completions in the browser, compare models and settings side by side, find your Runs again, read each token, and export Runs for Python.
  - [Use the Loom page](/docs/app/loom): Start a Loom in the browser, grow Branches under its Nodes, change the tree, use the keyboard, and export or import a Loom.

  - **Concepts**
  - [Base models](/docs/concepts/base-models): Why a Base model continues your text instead of answering it, why the API is strict, and why repeats differ.
  - [Budgets and Holds](/docs/concepts/budgets): How your monthly allowance, your Budget, and the Hold of each request decide how many tokens a request can use.
  - [The residual stream](/docs/concepts/residual-stream): What a read of the residual stream returns, how a Steering vector changes it, and how to choose a scale.
  - [Cold starts and long requests](/docs/concepts/long-requests): Why the first request to a cold model waits, how long the API waits for Inference, and how a request without a stream stays open.
  - [Work in the background](/docs/concepts/background-work): How the API runs Jobs, harvests, Loom Nodes, and Playground Runs without a client, in what order, and what happens when it restarts.

  - **Reference**
  - [Completions](/docs/completions): The request fields of POST /v1/completions and their defaults, the checks and size caps, and the fields of a Completion.
  - [Models](/docs/models): The Base models that the API serves, the fields and limits of each one, and the route that says whether a model is Warm or how far its start has got.
  - [Errors](/docs/errors): The error object, every status code that the API answers, the common errors with examples, and the error classes of the Python SDK.
  - [Limits](/docs/limits): Every limit of the API and the App in one place, for tokens, traffic, API keys, Jobs, harvests, Looms, request size, time, and kept data.
  - [Cheatsheet](/docs/cheatsheet): The smallest request for each task, with a link to the page that explains it, and the headers and error codes.
- API reference
  - [API reference](/docs/reference): Every route of the API, with its fields, its responses, and a playground.
  - Models
    - [List Models](/docs/reference/models/models.listModels): List the Base models that the API serves, each with its Model id, the Checkpoint it serves, its GPUs, and its capabilities: its context length, Layers, hidden size, and the limits of a request to it. `default` marks the model of a request without `model`. The API lists them from its settings and asks no Inference, so a list never starts a GPU.
    - [Retrieve Model](/docs/reference/models/models.retrieveModel): Return one model of GET /v1/models, as OpenAI's retrieve does. It asks no Inference.
    - [Get Model Status](/docs/reference/models/models.getModelStatus): Say whether the model's next request most likely starts at once (`warm`), or which stage its start has reached (`boot`). The API answers from what it saw and asks no Inference, so the route never starts a GPU.
  - Completions
    - [Create Completion](/docs/reference/completions/completions.createCompletion): Continue a prompt on a Base model. With `stream: true`, Server-Sent Events: one CompletionChunk per event, then `[DONE]`; with `output_residual_stream`, the last chunk has no choices and has the activations. If Inference fails, the error object with `type` `upstream_error`, the `code` that names the failure, and `retryable`; during a stream, that error is the last event before `[DONE]`.
  - Completionjobs
    - [Create Completion Job](/docs/reference/completionjobs/completionJobs.createCompletionJob): Queue one completion to run on the server, also after your connection closes. The body is a body of POST /v1/completions that does not stream. The request is admitted first, as POST /v1/completions admits it: a model that the API does not serve answers 400 `model_not_found`, a value that admission refuses answers 400, and if the token budget cannot hold it, 429 `budget_exceeded`; nothing is queued. Send an `Idempotency-Key` so that a retry gets the same job: the same key with another request answers 409 `idempotency_conflict`.
    - [Get Completion Job](/docs/reference/completionjobs/completionJobs.getCompletionJob): Return the job and its status. A 200 here does not mean that the completion succeeded: read GET /v1/completion-jobs/{job_id}/result.
    - [Get Completion Job Result](/docs/reference/completionjobs/completionJobs.getCompletionJobResult): Return the answer of an ended job, with the status that POST /v1/completions gave it: 200 and the Completion, or the error object with its own status, such as 429 `budget_exceeded` or 502. A cancelled job answers 409 `job_cancelled`, and a job that the server failed to run answers 500 `job_failed`. While the job is queued or running, 202 with the job and `Retry-After: 1`. 30 days after the job ended, 410 `job_result_expired`.
    - [Cancel Completion Job](/docs/reference/completionjobs/completionJobs.cancelCompletionJob): Cancel a queued or running job, and answer the job. A running job stops its Inference request. A job that ended stays as it is, and the answer is the same job.
  - Harvest
    - [Create Harvest](/docs/reference/harvest/harvest.createHarvest): Queue a harvest job: the residual stream of a Base model at the chosen layers, for each token of up to 4,096 prompts, written as files that you download by the links in its `result`. It holds the prompts' tokens while it runs and is charged the tokens the engine read. Only this route takes a body of up to 50 MiB. Answers the job, `pending`.
    - [Get Harvest](/docs/reference/harvest/harvest.getHarvest): Return the harvest job and its status. A `done` job has its `result`: a link for its manifest, its stats and each shard, which works 7 days and needs no API key; each answer makes new links. With `wait`, wait up to that many seconds for its status to change. An API key may have 4 such waits at once; past that, the answer comes at once with `X-Acs-Longpoll: declined` and `Retry-After: 3`.
    - [Cancel Harvest](/docs/reference/harvest/harvest.cancelHarvest): Cancel a pending or running harvest job, and stop its GPU run, also one that is still starting. A job that is running and whose GPU run started is charged the tokens it holds; any other cancel costs nothing. Answers the cancelled job, also for a second cancel.
  - Looms
    - [List Looms](/docs/reference/looms/looms.listLooms): List your Looms as Production does: the pinned ones first, then the others by their last change, newest first, at most 100, each with its name and prompt. Read a Loom for its Nodes.
    - [Create Loom](/docs/reference/looms/looms.createLoom): Make a Loom. Its root Node is the prompt. A retry with the same `Idempotency-Key` answers the Loom as it is now, or 404 if it was deleted since.
    - [Import Loom](/docs/reference/looms/looms.importLoom): Make a Loom from a file that GET /v1/looms/{loom_id}/export or Production's Loom export wrote, and answer it. Its Nodes get new ids; a Node keeps its text, its status (none is `completed`), its log probabilities and the Branch options it ran with.
    - [Export Loom](/docs/reference/looms/looms.exportLoom): Download the Loom as a file in Production's export shape (version 2): its title and last Branch settings, and each Node with its settings and marks, parents first. POST /v1/looms/import makes a Loom from it.
    - [Get Loom](/docs/reference/looms/looms.getLoom): Return the Loom: each Node with its status and text. Read it again to follow a Branch.
    - [Update Loom](/docs/reference/looms/looms.updateLoom): Rename or pin the Loom, and answer it. A rename moves it to the top of its unpinned Looms; a pin puts it above them.
    - [Delete Loom](/docs/reference/looms/looms.deleteLoom): Delete the Loom and all its Nodes. You cannot undo it. While a Node of the Loom is `queued` or `running`, 409 and the error object.
    - [Stream Loom](/docs/reference/looms/looms.streamLoom): Follow a Loom as Server-Sent Events: each Node of the Loom, then each Node again when its status or text changes, then `[DONE]` when no Node is `queued` or `running`. A running Node's text is its whole text so far, at most every 250 ms.
    - [Cancel Loom](/docs/reference/looms/looms.cancelLoom): Stop each Node of the Loom that is `queued` or `running`, and answer the Loom. Each becomes `cancelled`: a running Node keeps the text it grew, and its tokens so far are charged; a queued Node never runs and holds nothing.
    - [Create Branch](/docs/reference/looms/looms.createBranch): Grow a Branch under a completed Node: `n` child Nodes, each one Completion of its text. The text of a Node is the text on the path from the root to it. The server writes the new Nodes as their tokens arrive, also when no client is connected. Answers the new Nodes, `queued`. For a Node that is not completed, 409 and the error object. For a model that the API does not serve, 400 `model_not_found`, and no Node is made. If the token budget cannot hold one Node's Completion, 429 `budget_exceeded` and no Node is made.
    - [Set Root](/docs/reference/looms/looms.setRoot): Replace the Loom's tree with one root, the text you write, and answer the Loom. While a Node of the Loom is `queued` or `running`, 409.
    - [Edit Node](/docs/reference/looms/looms.editNode): Rewrite the Node's text, and answer the Loom. A new text drops the Node's log probabilities, as they were of the old one; the same text changes nothing. For a failed Node, or while a Node under it is `queued` or `running`, 409.
    - [Delete Node](/docs/reference/looms/looms.deleteNode): Delete the Node and every Node under it, and answer the Loom without them. You cannot undo it. For the root, or while a Node to delete is `queued` or `running`, 409 and the error object.
    - [Split Node](/docs/reference/looms/looms.splitNode): Cut the Node at `offset`, and answer the Loom. The Node keeps the text before the cut; a new child gets the text after it, and the Node's children move under the child, so every path keeps its text. A cut of the Node's own text gives each half the log probabilities of its whole tokens; the child's `request` has no seed, as a part of a sample cannot be sampled again. For a failed Node, a Loom of 2,000 Nodes, or while a Node under it is `queued` or `running`, 409.
    - [Add Sibling](/docs/reference/looms/looms.addSibling): Write a Node beside this one, under the same parent, and answer the Loom. For a root, a Loom of 2,000 Nodes, or while a Node under the parent is `queued` or `running`, 409.
  - Health
    - [Health](/docs/reference/health/health.health): Return the state of the API in v1's shape: `ok`, `degraded` with its `degraded_reasons`, or `down`. It checks the database on its own connection, whether a pooled connection is free, and each runner, and never asks Inference. `backends` gives each served model's breaker and requests in flight, and `degraded_backends` the models whose breaker is open. 503 only when the database does not answer within `HEALTH_TIMEOUT`; a degraded API answers 200.
  - Chat
    - [Create Chat Completion](/docs/reference/chat/chat.createChatCompletion): Not served: Base models have no chat format. Always answers 400, naming POST /v1/completions.
- Cookbook
  - [Cookbook](/docs/cookbook): Recipes that each do one task from start to end, with a program or a script that you copy and run.

  - **Run work**
  - [Run a Job from a shell script](/docs/cookbook/job-script): Submit a Job with curl, wait until it ends, and save its result to a file.
  - [Download a harvest from a shell script](/docs/cookbook/harvest-script): Submit a harvest with curl, wait until it ends, and download its manifest, statistics, and shards into a folder.

  - **Handle your Budget**
  - [Handle the end of your Budget](/docs/cookbook/budget-cap): Detect when the API lowers max_tokens to fit your tokens, handle the 429 errors in code, and find what holds your tokens.

  - **Measure text**
  - [Score a text](/docs/cookbook/score-a-text): Get the log-likelihood of a text that you already have, from the log probability of each of its tokens.
  - [Evaluate with Inspect](/docs/cookbook/evaluate-with-inspect): Run an Inspect eval on a Base model through POST /v1/completions, with raw prompts and no chat template.

  - **Steer**
  - [Steer with a contrast vector](/docs/cookbook/contrast-steering): Build a Steering vector from the Activations of two sets of prompts, and steer a Base model with it at a few scales.

  - **Learn in a notebook**
  - [Run the workshop notebook](/docs/cookbook/workshop): Open the workshop's Jupyter notebook, which goes from a first Completion to a steered Base model, with an exercise in each section after the setup.
- Tutorials
  - [Tutorials](/docs/tutorials): Lessons that build a small, working result against the API, one step at a time, with the output to expect at each step.
  - [Your first steered Completion](/docs/tutorials/first-steered-completion): Get access, make an API key, run a Completion, read its Activations at one Layer, and steer that Layer with a Steering vector.
  - [Sample many rollouts](/docs/tutorials/sample-many-rollouts): Sample many continuations of two prompts, first in one request, then in many requests at once, then in a Job that runs in the background.
- Changelog
  - [Changelog](/docs/changelog): What changed for Users of the API and the App, newest first.
- Support
  - [Support](/docs/support): Write to us for help, report a bug with what we need to reproduce it, ask for more tokens, and join ACS's Discord server.
  - [Research preview](/docs/support/research-preview): The platform rules that you agree to when you apply for ACS Infra, and what research preview means for your work.
  - [FAQ](/docs/support/faq): Short answers to the questions that Users ask, each with a link to the page that explains it.