# Time zones

> Page: https://docs.flung.dev/time-zones. Index of every page: https://docs.flung.dev/llms.txt

Schedule a post at the time a person said, in their own time zone, and let Flung work out the instant. Every time is kept in UTC; a zone only says how a time is read and shown.

## TL;DR

| Question | Answer |
|---|---|
| What does Flung store? | Every time in UTC. Answers give `publishAt` in UTC, ending in `Z`. |
| Can I send a local time? | Yes: `publishAt: "2026-11-03T09:00"`, with no offset, and an optional `timeZone` such as `Europe/Athens`. |
| Which zone is used without `timeZone`? | The person's own for an app a person approved and for an agent signed in, the workspace's default for an API key, else UTC. |
| How do I see what was used? | Each post has `publishAtLocal` and `timeZone` beside `publishAt`. [Who is calling](https://docs.flung.dev/reference/api/get-v1-me.md) says the caller's zone and the time there now. |
| Do times with an offset still work? | Yes, exactly as before: `2026-11-03T09:00:00+02:00` and `2026-11-03T07:00:00Z` are instants as they stand. |
| What if the clocks change at that time? | A skipped time moves forward by the gap, a repeated one takes the earlier instant, and the answer has a `warnings` entry. |

## Two ways to give a time

`publishAt` takes either form, on [Schedule a post](https://docs.flung.dev/reference/api/post-v1-posts.md), [Change a scheduled post](https://docs.flung.dev/reference/api/patch-v1-posts-id.md) and [Schedule a post from a template](https://docs.flung.dev/reference/api/post-v1-templates-id-deploy.md):

| You send | Flung reads it as |
|---|---|
| `2026-11-03T07:00:00Z` | That instant, 07:00 UTC. |
| `2026-11-03T09:00:00+02:00` | That instant, 07:00 UTC: the offset says where. |
| `2026-11-03T09:00` with `timeZone: "Europe/Athens"` | 09:00 in Athens that day, 07:00 UTC in November. |
| `2026-11-03T09:00` alone | 09:00 in the caller's zone, as below. |

A local time is the clock on the wall: the same 09:00 in Athens is 07:00 UTC in winter and 06:00 UTC in summer, and Flung follows the change for you. Send a local time when a person said "9am"; send an instant when your own system already has one.

`timeZone` is an IANA name, such as `Europe/Athens`, `America/New_York`, `Australia/Sydney` or `Asia/Kathmandu`. Abbreviations such as `EET` and bare offsets such as `+02:00` are not zones, and are refused with `422` and the code `invalid_time_zone`. With an instant, `timeZone` changes nothing about when the post goes; it names the zone `publishAtLocal` is written in.

## The caller's zone

When a request names no `timeZone`, Flung reads a local time in the first of these that is set:

| Order | Zone | Set by |
|---|---|---|
| 1 | The request's `timeZone` | You, on each call. |
| 2 | The person's own | Their Account page in the Flung portal. Used for an app a person approved with OAuth, and for an AI agent they signed in. |
| 3 | The workspace's default | An owner, in the workspace's settings in the portal. Used for an API key, which belongs to the workspace, not a person. |
| 4 | UTC | Nobody has said a zone. |

A person's zone is set the first time they sign in, from where they sign in from, and they can change it at any time; a zone they chose is never replaced. [Who is calling](https://docs.flung.dev/reference/api/get-v1-me.md) answers the zone a call would use, where it came from (`timeZoneSource`: `user`, `workspace` or `default`), and the time now in UTC (`now`) and there (`nowLocal`):

**curl**

```bash
curl -X GET 'https://api.flung.dev/v1/me' \
  --header "Authorization: Bearer $FLUNG_API_KEY"
```

**TypeScript**

```ts
import { Flung } from '@flung.dev/sdk'

const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })
const result = await flung.me.get()
```

**fetch**

```js
const response = await fetch('https://api.flung.dev/v1/me', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.FLUNG_API_KEY}`,
  },
})
if (!response.ok) throw new Error((await response.json()).error.message)
const result = await response.json()
```

[Suggest posting times](https://docs.flung.dev/reference/api/get-v1-posting-times.md) uses the caller's zone too when you leave out its `timeZone`, and each time it suggests carries that zone's offset, ready for `publishAt`.

## What comes back

Every post, from creating, changing, reading and listing it, and in webhook payloads, says its time three ways:

| Field | Example | Meaning |
|---|---|---|
| `publishAt` | `2026-11-03T07:00:00.000Z` | When it publishes, in UTC. |
| `publishAtLocal` | `2026-11-03T09:00:00+02:00` | The same instant as the local time in `timeZone`, with that day's offset. |
| `timeZone` | `Europe/Athens` | The zone the time was given in. A post from before zones were kept shows the caller's. |

Show a person `publishAtLocal`, and compare and sort by `publishAt`.

## When the clocks change

Twice a year, many zones skip an hour or repeat one. In Athens the clocks go from 03:00 to 04:00 on the last Sunday of March, and from 04:00 back to 03:00 on the last Sunday of October.

| You send, in `Europe/Athens` | That day | Flung schedules | `warnings` |
|---|---|---|---|
| `2026-03-29T03:30` | 03:30 never happens | 04:30 local, `01:30Z`: moved forward by the gap | `local_time_skipped` |
| `2026-10-25T03:30` | 03:30 happens twice | The first one, still on summer time, `00:30Z` | `local_time_ambiguous` |
| `2026-10-25T04:00` | Once | `02:00Z` | None |

A `warnings` entry has a `code` and a `message` for a person, and appears only on the answer that created or changed the post. To pick the second 03:30 of a repeated hour, send it with its offset, `2026-10-25T03:30:00+02:00`.

## AI agents

The [MCP server](https://docs.flung.dev/mcp.md) works the same way, so an agent never does time-zone arithmetic. Its scheduling tools take `publishAt` as the local time the person said, and `timeZone` only when they named a place ("9am Athens time"). The answer gives `publishAt` in UTC with `publishAtLocal` and `timeZone`, so the agent can confirm the time back in the person's own words. The `get_time` tool says the person's zone and the time there now, for turning "tomorrow morning" into a date. See [schedule_post](https://docs.flung.dev/mcp/tools/schedule-post.md) and [get_time](https://docs.flung.dev/mcp/tools/get-time.md) in the tool reference.

## In the portal

On the Account page, the Time zone field shows the zone dates are written in for you, with its offset from UTC and the time there now. It says when it was set from your location; choose another at any time. A workspace's owners set its default zone, for its API keys, in the workspace's settings. Every date and time in the portal is shown in your zone, with the zone's short name where the time matters. To move a scheduled post, open it on the Activity page and choose Change time: pick the new time in your zone, and the field shows it in UTC too before you save.