batches

Prepare or refine the plan

Natural-language back and forth. Send instruction to (re)plan from scratch, or refinement to adjust the current plan ("actually, only the empty rows"). The response embeds the rebuilt plan with measured counts and a 10-item preview of real extractions. Nothing is charged until approval; check plan.not_included — a non-empty list means part of the instruction will NOT happen.

POST/v1/batches/{batch_id}/plan

Request

curl --request POST \
  --url 'https://api.ai-glot.com/v1/batches/<batch_id>/plan' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "instruction": "<string>",
  "refinement": "<string>"
}'

import json
import requests

url = "https://api.ai-glot.com/v1/batches/<batch_id>/plan"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"instruction\":\"<string>\",\"refinement\":\"<string>\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.ai-glot.com/v1/batches/<batch_id>/plan", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "instruction": "<string>",
    "refinement": "<string>"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.ai-glot.com/v1/batches/<batch_id>/plan");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"instruction\":\"<string>\",\"refinement\":\"<string>\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://api.ai-glot.com/v1/batches/<batch_id>/plan", bytes.NewBuffer([]byte("{\"instruction\":\"<string>\",\"refinement\":\"<string>\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.ai-glot.com/v1/batches/<batch_id>/plan"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"instruction\":\"<string>\",\"refinement\":\"<string>\"}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.ai-glot.com/v1/batches/<batch_id>/plan")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"instruction\":\"<string>\",\"refinement\":\"<string>\"}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "data": {
    "id": "<string>",
    "name": "<string>",
    "file_name": "<string>",
    "status": "analyzing",
    "quality_tier": "<string>",
    "word_count": 123,
    "credit_cost": 123,
    "is_sample": true,
    "archived": true,
    "progress": {
      "phase": "<string>",
      "percent": 123.45,
      "updated_at": "<string>",
      "estimated_seconds_remaining": 123
    },
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "created_at": "<string>",
    "completed_at": "<string>",
    "next_action": "provide_instruction",
    "plan": {
      "instruction": "<string>",
      "summary": "<string>",
      "will_translate": "<string>",
      "will_not_touch": "<string>",
      "special_rules": [
        "<string>"
      ],
      "assumptions": [
        "<string>"
      ],
      "not_included": [
        "<string>"
      ],
      "languages": [
        {
          "source": {},
          "target": {},
          "segments": {},
          "words": {}
        }
      ],
      "totals": {
        "segments": 123,
        "words": 123,
        "files": {}
      },
      "credits": {
        "standard": 123,
        "lite": 123
      },
      "preview": [
        {
          "location": {},
          "source_text": {},
          "source_lang": {},
          "target_lang": {}
        }
      ],
      "cached": true
    },
    "suggested_instructions": [
      "<string>"
    ]
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>"
  },
  "request_id": "<string>"
}

Requires batches:create. Planning is free and repeatable: nothing is charged until you approve.

Send one or the other, not both.

Field	Meaning
`instruction`	Plan from scratch. Replaces any previous plan entirely.
`refinement`	Adjust the plan that already exists: “actually, only the empty rows”, “leave the URLs alone”.

The distinction matters when a plan is nearly right: refinement keeps everything you already agreed to, while instruction starts over and may reinterpret parts you were happy with.

Read the plan before approving

The response embeds the rebuilt plan with measured counts (the actual number of items and words found in your file, not an estimate from its size), plus a preview of ten real extractions.

Those ten are the cheapest check available. They show the exact strings that will be sent for translation, so an instruction that quietly matched the wrong field is visible before it costs anything.

Response

application/json

Prepare or refine the translation plan

dataobjectrequired

Show child attributes

idstringrequired

namestring | nullrequired

file_namestring | nullrequired

statusstringrequired

Where the translation is. All seven values: analyzing — the file's structure is being read, which takes seconds; poll. awaiting_instructions — the file is read, nobody has said what to translate; call plan. awaiting_approval — a plan is waiting for a yes; call approve, the only call that spends credits. translating — running; poll. completed — fetch the result. failed — the run could not finish; read error. cancelled — someone stopped it on purpose; also terminal, and not a failure. The last three are terminal: stop polling.

quality_tierstring | nullrequired

word_countinteger | nullrequired

credit_costinteger | nullrequired

is_samplebooleanrequired

archivedbooleanrequired

progressobjectrequired

errorobject | nullrequired

created_atstring | nullrequired

completed_atstring | nullrequired

next_actionstring

The call to make next, so a client never has to map status itself. provide_instruction — call plan with an instruction. review_plan — the priced plan is embedded; check plan.not_included, then approve. wait — poll again; progress.estimated_seconds_remaining says how long is left. download — fetch the result. read_error — the run is over without a result; read error (and status says whether it broke or was cancelled). Absent only on a legacy pre-2026-08-31 CSV batch, which has no plan behind it; every translation created since then answers.

planobject | null

suggested_instructionsstring[] | null

request_idstringrequired

Prepare or refine the plan

Instruction or refinement

Read the plan before approving

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown