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. Account context can be configured in your account settings to give Gale information about your operations, internal protocols, or other relevant guidance, so its responses are tailored to your needs.
`includeLinks`	boolean	No	`false`	When `true`, the response includes "explore-on-map" link that leads to the platform map with the location anchored and relevant setup to the answer- selected layers, timeframe, etc. Only accounts with permissions to platform can use the link.
`language`	string	No	account default	Response language.
`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 identifier. Omit to start a new conversation (a new `sessionId` is returned), or pass a previous `sessionId` to continue that conversation with its earlier context.

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

{
    "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.

{
    "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": "In **Boston, MA, USA**, tomorrow's weather shows some mixed conditions 	regarding rain:\n\n- **Precipitation Probability**: Increases to as high as **70%** around mid-morning to the afternoon.\n- **Rain Accumulation**: During these higher probabilities, rain intensity could reach up to **3.73 mm/hr**.\n\nOverall, it's a good idea to be prepared with an umbrella or rain gear, especially in the afternoon and early evening when rain is expected to peak. The earlier part of the day is expected to be relatively dry.",
		"id": "162268957202136965",
    "sessionId": "c0077d39-3ba7-431a-ab88-514f6ec8259e",
    "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 use 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 to start a fresh conversation.

{
  "question": "What about the day after?",
  "sessionId": "c0077d39-3ba7-431a-ab88-514f6ec8259e"
}

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."
  }
}

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

Body parameters

Example Request

Response

Continuing a Conversation

Tip

Errors