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

# Get the next best time for each account

> Each account is scored on its own history, as in *Get the best times to post*, and its next best time is the soonest of its `best` slots after `from`. That is always within a week, and never in the past. Accounts with no best slot yet are left out of `times`.

Read-only. Personal access tokens may call it with any workspace role, viewers included.

**Required permission:** `publishing:analytics:read`



## OpenAPI

````yaml /api-reference/publishing.openapi.json get /{workspace}/analytics/best-times
openapi: 3.1.0
info:
  title: Publishing API
  version: 1.0.0
  description: >-
    Social accounts, posts, scheduling, approval, tags, media and analytics for
    one workspace.
servers:
  - url: https://app.onlysocial.io/os/api
    description: OnlySocial
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Diagnostics
  - name: Accounts
  - name: Posts
  - name: Media
  - name: Tags
  - name: Analytics
    description: >-
      Followers, reach, engagement and post performance, as the analytics
      dashboard shows them, plus when to post. Dates are UTC days unless a
      `timezone` is sent. Figures compared with the previous period of the same
      length are `{value, change}`, where `change` is a percentage (`100` when
      the previous period was zero, `null` when both are). Time series are lists
      of `{date, value}` points; breakdowns (ages, countries, keywords) are
      lists of `{label, value}`.
paths:
  /{workspace}/analytics/best-times:
    get:
      tags:
        - Analytics
      summary: Get the next best time for each account
      description: >-
        Each account is scored on its own history, as in *Get the best times to
        post*, and its next best time is the soonest of its `best` slots after
        `from`. That is always within a week, and never in the past. Accounts
        with no best slot yet are left out of `times`.


        Read-only. Personal access tokens may call it with any workspace role,
        viewers included.


        **Required permission:** `publishing:analytics:read`
      operationId: analytics.bestTimes
      parameters:
        - name: workspace
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Your workspace UUID. Must match the API key's workspace.
        - name: accounts[]
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Account UUIDs. Defaults to every account in the workspace.
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: >-
            A day in `timezone` to look from. Defaults to now; a day in the past
            counts as now.
        - name: timezone
          in: query
          schema:
            type: string
            example: Europe/Berlin
          description: >-
            IANA timezone the weekdays, hours and times are in. Defaults to the
            timezone setting of the key's creator (or the token's user), then
            UTC.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BestTimes'
        '401':
          description: Missing or invalid credential.
        '403':
          description: The API key does not have `publishing:analytics:read`.
        '404':
          description: Unknown workspace, account or post.
        '422':
          description: >-
            Invalid input. An account that is not in the workspace, an unknown
            timezone, or `from` not `YYYY-MM-DD`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
components:
  schemas:
    BestTimes:
      type: object
      properties:
        timezone:
          type: string
        times:
          type: array
          items:
            type: object
            properties:
              account_id:
                type: integer
              account_uuid:
                type: string
                format: uuid
              date:
                type: string
                format: date
              time:
                type: string
                example: '13:00'
                description: 24-hour, in `timezone`.
    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: The date range may span at most 366 days.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            date_to:
              - The date range may span at most 366 days.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A workspace API key: `Authorization: Bearer osk_...`'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: The same workspace API key in the `x-api-key` header.

````

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