> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genviral.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Suggested Post Slot

> Suggest the next free time to post to one or more accounts, based on the posting times set for them in Genviral.

Returns the next free time to post to the accounts you name. Nothing is scheduled: pass the
returned `scheduled_at` to [Create Post](/api-reference/create-post) when you want the post to go
out at that time.

## Behavior

* Candidate times are the posting times set for these accounts in the Genviral Social Hub (the
  same `posting_times` that [Get Accounts](/api-reference/get-accounts) returns), combined across
  all named accounts. When none of them has posting times, the candidate is 12:00 each day.
* Posting times are wall-clock times. They are read in the `timezone` you send, so `09:00` means
  9 in the morning in that zone.
* The search starts today in that zone and never suggests a time less than two minutes from now.
* A time is skipped when one of these accounts already has a post scheduled in that same minute.
  `skipped_conflicts` counts the skipped times.
* Every account must belong to the key scope (workspace accounts for a workspace key, personal
  accounts for a personal key) and be active. Otherwise the request fails with
  `400 validation_failed`.

## Query Parameters

<ParamField query="account_ids" type="string" required>
  Comma-separated account IDs from [Get Accounts](/api-reference/get-accounts). Between `1` and
  `10` IDs. Repeated IDs are counted once.
</ParamField>

<ParamField query="timezone" type="string" required>
  IANA time zone the suggestion is computed in, for example `Europe/Amsterdam` or
  `America/New_York`.
</ParamField>

## Response

<ResponseField name="scheduled_at" type="string">
  Suggested time as an ISO 8601 timestamp in UTC.
</ResponseField>

<ResponseField name="source" type="string">
  Where the time came from: `account_posting_times` (the accounts' own posting times) or
  `fallback_noon` (no posting times are set, so noon was used).
</ResponseField>

<ResponseField name="skipped_conflicts" type="number">
  How many earlier candidate times were skipped because one of the accounts already had a post
  scheduled then.
</ResponseField>

<ResponseField name="timezone" type="string">
  The time zone the suggestion was computed in, echoed from the request.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://www.genviral.io/api/partner/v1/posts/suggested-slot?account_ids=0f4f54d4-8cce-4fb7-8c7b-befbcb8af812,54c22677-43f4-415f-a820-7dfd1fcd4bd5&timezone=Europe/Amsterdam' \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Suggested slot retrieved",
    "data": {
      "scheduled_at": "2026-10-03T07:00:00.000Z",
      "source": "account_posting_times",
      "skipped_conflicts": 1,
      "timezone": "Europe/Amsterdam"
    }
  }
  ```

  ```json Accounts not in scope theme={null}
  {
    "ok": false,
    "code": 400,
    "message": "No time could be suggested. Check that every account is connected and active in this space.",
    "error_code": "validation_failed"
  }
  ```
</ResponseExample>

## Error Responses

* `400 validation_failed` - one or more accounts are outside the key scope or are not active
* `401` - authentication failed (missing, invalid, or revoked token)
* `422 invalid_payload` - `account_ids` or `timezone` is missing or invalid; `fields` names each
  one
* `500` - unexpected error while computing the suggestion


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.