Ask a Weather Question

POST: https://api.tomorrow.io/v4/gale-ai/chat

Body parameters

Field	Type	Required	Default	Description
`question`	string	Yes	—	The weather question. May contain `{{index}}` placeholders that map to `metadata` entries (see below).
`prompt`	string	No	—	Extra per-request guidance for the agent, applied on top of your account's context.
`includeLinks`	boolean	No	`false`	When `true`, the response includes "explore-on-map" link that leads to the platform map with the location anchored. Only accounts with permissions to platform can use the link.
`language`	string	No	account default	Response language. Overrides your account language when provided.
`units`	string	No	`metric`	Unit system: `metric` or `imperial`.
`timezone`	string	No	location-local	IANA timezone (e.g. `America/New_York`) used for time phrasing. Invalid zones return `400`. Omit to use each location's local timezone.
`metadata`	array	No	—	Typed entity references for `{{index}}` placeholders in the question. `{{0}}` → `metadata[0]`, `{{1}}` → `metadata[1]`, and so on. Omit to let Gale resolve the location from the question text.
`sessionId`	string	No	new session	Conversation id to continue. Echo the `sessionId` from a previous response to resume the conversation. Omit to start a new one- the response returns a new id.

Each metadata entry:

Field	Type	Required	Description
`type`	string	Yes	Entity type. Currently only `locationId` is supported.
`value`	string	Yes	The entity value- currently only location id is supported.

Example Request

curl -X POST "https://api.tomorrow.io/v4/gale-ai/chat?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will it rain tomorrow in Boston?"
  }'

To reference a location id instead of specifying it in the question- Use {{index}} placeholders in the question and pass the matching entities in metadata. The location is resolved directly from the id — no guessing from the text.

curl -X POST "https://api.tomorrow.io/v4/gale-ai/chat?apikey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will it rain tomorrow in {{0}}?",
    "metadata": [
      { "type": "locationId", "value": "12345678" }
    ],
    "units": "metric",
    "includeLinks": true
  }'

Response

200 OK — header X-Quota-Remaining-Gale: <integer>

{
  "data": {
    "answer": "Yes — light rain is expected tomorrow afternoon, tapering off by evening.",
    "id": "req_abc123",
    "sessionId": "789",
    "links": {
      "map": "https://app.tomorrow.io/map?..."
    }
  }
}

Field	Type	Description
`data.answer`	string	Natural-language answer.
`data.id`	string	Request id (use it when contacting support).
`data.sessionId`	string	Conversation id. Send it back as `sessionId` on your next call to continue the conversation.
`data.links.map`	string	Link to explore the answer on the map. Present only when `includeLinks` is `true` and a link is available.

Continuing a Conversation

Gale keeps conversation history so follow-up questions have context.

How it works

On your first call, the response returns a server-issued sessionId.
Send that same sessionId on the next call to continue the conversation. Gale replays the recent turns as context, so you can ask follow-ups that refer back to earlier answers (e.g. "What about the day after?").
Omit sessionId (or send a new one) to start a fresh conversation.

{
  "question": "What about the day after?",
  "sessionId": "789"
}

Good to know

History is scoped to your account- a sessionId only ever accesses your own conversation.
A conversation stays active for 24 hours after your last call, then expires. Any call within that window refreshes the timer.

📘
Tip
Persist the sessionId for the duration of a user's session so every follow-up question stays in context.

Errors

Status	Meaning
`400`	Invalid timezone, unknown `metadata` type, an `{{index}}` placeholder with no matching `metadata` entry, or a malformed body.
`402`	No Gale interactions remaining (`GALE_QUOTA_LIMIT_REACHED`).
`404`	A `metadata` entity id does not exist.
`500`	Unexpected server error.

Error responses use the shape:

{
  "data": {
    "error": "Description of what went wrong."
  }
}