openapi: 3.0.3
info:
  title: Brightcove Analytics API Reference Access Tokens History API
  description: "Reference for the Brightcove Analytics API, used to retrieve analytics data for your accounts. To test API requests, you can use our <a href=\"/getting-started/concepts-testing-tools-brightcove-apis.html\" target=\"_blank\">API Testing Tools</a>.\n\nFor additional in-depth guides to features of the API, see the **[general documentation](/analytics/index.html)**.\n\n **Base URL**: https://analytics.api.brightcove.com"
  x-bc-access: public
  version: 1.0.0
servers:
- url: https://analytics.api.brightcove.com
  variables: {}
tags:
- name: History
  description: Operations for getting the history of all or a specific video.
paths:
  /accounts/{{account_id}}/videos/history:
    get:
      tags:
      - History
      summary: List the lifetime social history for every video on the account.
      description: Gets the lifetime history of every video Social has ever attempted to distribute to a social platform.  Note that this endpoint has pagination.
      operationId: getAccountVideosHistory
      security:
      - BC_OAuth2:
        - video-cloud/social/status/read
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/Platform'
      - $ref: '#/components/parameters/DestinationId'
      - $ref: '#/components/parameters/Status'
      - $ref: '#/components/parameters/Before'
      - $ref: '#/components/parameters/Since'
      - $ref: '#/components/parameters/PageKey'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: A list of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoList'
        '403':
          description: Forbidden
        '422':
          description: Invalid query parameters
        '500':
          description: Server error
  /accounts/{{account_id}}/videos/{{video_id}}/history:
    get:
      tags:
      - History
      summary: List the lifetime social history the video.
      description: Gets the lifetime history of the requested video for every Social Destination is has ever been distributed to.  Note that this endpoint has pagination.
      operationId: getAccountVideoHistory
      security:
      - BC_OAuth2:
        - video-cloud/social/status/read
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/VideoId'
      - $ref: '#/components/parameters/Platform'
      - $ref: '#/components/parameters/DestinationId'
      - $ref: '#/components/parameters/Status'
      - $ref: '#/components/parameters/Before'
      - $ref: '#/components/parameters/Since'
      - $ref: '#/components/parameters/PageKey'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: A list of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoList'
        '403':
          description: Forbidden
        '422':
          description: Invalid query parameters
        '500':
          description: Server error
components:
  schemas:
    VideoList:
      type: object
      properties:
        total_hits:
          type: integer
        page_key:
          type: string
        videos:
          type: array
          items:
            $ref: '#/components/schemas/Video'
      example:
        total_hits: 117
        page_key: 1506960062695:5382545592001_-T6xvfm_ebE
        videos:
        - id: '5667310879001'
          account_id: '1486906377'
          destination_id: c1243033-fbfd-4f1d-80e4-00ed027db9ec
          remote_id: hWESxu2PZFU
          remote_url: https://www.youtube.com/watch?v=hWESxu2PZFU
          status: PUBLISHED
          timestamp: Jan 26, 2018 6:59:16 PM
          published_at: Jan 26, 2018 6:59:16 PM
          distribution_method: MANUAL
          action: YOUTUBE_UPLOAD
          result: SUCCESS
        - id: '5263118111001'
          account_id: '1486906377'
          destination_id: 9b67c5f2-5fed-4b61-8383-7bb6e4456b8e
          remote_id: '1434615919981329'
          remote_url: https://www.facebook.com/1434615919981329
          status: SYNCED
          timestamp: Jan 24, 2018 3:35:24 PM
          published_at: Jan 24, 2018 3:35:24 PM
          distribution_method: SYNC
          autosync_id: 4d09778b-0043-4be6-8dd7-011863607f0c
          action: FACEBOOK_UPDATE
          result: SUCCESS
        - id: '5363058704001'
          account_id: '1486906377'
          destination_id: 9b67c5f2-5fed-4b61-8383-7bb6e4456b8e
          status: ERROR
          timestamp: Dec 8, 2017 6:44:49 PM
          published_at: Dec 8, 2017 6:44:49 PM
          distribution_method: MANUAL
          errors:
          - error_code: UPLOAD_FAILURE
            message: 'Upload error: Received Facebook error response of type OAuthException: (#100) sponsor_id requires publishing profile/page to be verified or branding partner. (code 100, subcode null)'
          action: FACEBOOK_UPLOAD
          result: ERROR
        - id: '5630023626001'
          account_id: '1486906377'
          destination_id: 69cac3e2-4e71-489f-86f4-c00ae7e9e235
          remote_id: GcFEO8hEiw8
          remote_url: https://www.youtube.com/watch?v=GcFEO8hEiw8
          status: PUBLISHED
          timestamp: Oct 31, 2017 3:49:02 PM
          published_at: Oct 31, 2017 3:49:02 PM
          distribution_method: MANUAL
          action: YOUTUBE_UPLOAD
          result: SUCCESS
        - id: '5382545592001'
          account_id: '1486906377'
          destination_id: 7d6a1691-317e-4142-a59c-a2bbc28bf08d
          remote_id: 8z9uAFW24Zs
          remote_url: https://www.youtube.com/watch?v=8z9uAFW24Zs
          status: ABANDONED
          timestamp: Oct 2, 2017 5:07:48 PM
          published_at: Oct 2, 2017 5:07:48 PM
          distribution_method: SYNC
          autosync_id: 83440ca9-ca3b-43d4-b75f-a606efe03433
          action: YOUTUBE_UPDATE_UNSYNC
          result: SUCCESS
        - id: '5382545592001'
          account_id: '1486906377'
          destination_id: 7d6a1691-317e-4142-a59c-a2bbc28bf08d
          remote_id: -T6xvfm_ebE
          remote_url: https://www.youtube.com/watch?v=-T6xvfm_ebE
          status: DELETED
          timestamp: Oct 2, 2017 4:01:02 PM
          published_at: Oct 2, 2017 4:01:02 PM
          distribution_method: SYNC
          autosync_id: 83440ca9-ca3b-43d4-b75f-a606efe03433
          action: YOUTUBE_DELETE
          result: SUCCESS
    Error:
      type: object
      properties:
        error_code:
          type: string
          description: The error code returned recorded by the server, from the social platform, if any.
        error_message:
          type: string
          description: The error message recorded by the server, or returned from the social platform, if any.
        platform_error:
          type: string
          description: JSON representation of the error object returned from the social platform, if any.
    Video:
      type: object
      properties:
        id:
          type: string
          description: Brightcove ID for the video
        account_id:
          type: string
          description: Brightcove ID of the account that owns this video
        destination_id:
          type: string
          description: Brightcove ID for the Social destination for which this status is reported
        remote_id:
          type: string
          description: Remote social platoforms ID for this video
        remote_url:
          type: string
          format: url
          description: URL to the video on the remote social platform. Optional. Only exists if the video has PUBLISHED or SYNCED status.
        status:
          type: string
          description: Socials last known status for the video on the remote platform
          enum:
          - PUBLISHED
          - DELETED
          - ERROR
          - HIDDEN
          - NOT_FOUND
          - SCHEDULED
          - SYNCED
          - ABANDONED
        timetamp:
          type: string
          format: date-time
          description: Timestamp at which this status was reported
        published_at:
          type: string
          format: date-time
          description: Timestamp at which the video was scheduled to be made visible on the remote social platform.  May be the same as `timestamp` if the video was to be made visible immediately.
        distribution_method:
          type: string
          description: The mechanism which initiated the operation that put the video in this status.  `SYNC` if the most recent video operation was initiated by an AutoSync.  `MANUAL` if the video was distribution manually through the Social Studio module.
          enum:
          - MANUAL
          - SYNC
        autosync_id:
          type: string
          description: Brightcove ID of the AutoSync that triggered this status.  Optional. Only exists if the `distribution_method` is `SYNC`
        error:
          $ref: '#/components/schemas/Error'
        warning:
          $ref: '#/components/schemas/Error'
        action:
          type: string
          description: The action attempted during this operation.
          enum:
          - UPLOAD
          - UPDATE_SYNC
          - UPDATE_UNSYNC
          - DELETE
        result:
          type: string
          description: The result of this operation.
          enum:
          - SUCCESS
          - ERROR
  parameters:
    Platform:
      name: platform
      in: query
      description: 'Limit the list of videos to a single social platform.  Valid values for this property are

        - YOUTUBE

        - FACEBOOK

        - TWITTER


        Note that this may conflict with `destination_id`, below.'
      required: false
      schema:
        type: string
        enum:
        - YOUTUBE
        - FACEBOOK
        - TWITTER
    VideoId:
      name: video_id
      in: path
      description: ID of the video to query video statuses for
      required: true
      schema:
        type: string
    AccountId:
      name: account_id
      in: path
      description: ID of the account to query video statuses for
      required: true
      schema:
        type: string
    PageKey:
      name: page_key
      in: query
      description: Fetch the next page of data.  If the previous call to this endpoint returned a `page_key`, a subsequent call can be made with the same parameters and including the `page_key` to retrieve the next page.
      required: false
      schema:
        type: string
    PrettyPrint:
      name: pretty_print
      in: query
      description: Whether or not to pretty-print the JSON response.  Defaults to false.
      required: false
      schema:
        type: boolean
    Before:
      name: before
      in: query
      description: Limit the list of videos to those whose last status change occurred before the specified date time.  Can accept either a full timestamp, or just a datestamp.  If passed just a datestamp, assumes 00:00:00 for the time, and the filter will be exclusive of the date specified.
      required: false
      schema:
        type: string
        format: date-time
    PageSize:
      name: page_size
      in: query
      description: The number of entries to fetch in the next page of data.  Must be a number between 1 and 100, inclusive.  Defaults to 20.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
    Status:
      name: status
      in: query
      description: "Limit the list of videos to those with a specific status.  Valid values for this property are\n  - DELETED\n  - ERROR\n  - HIDDEN\n  - PROCESSING\n  - PUBLISHED\n  - SCHEDULED\n  - SYNCED\n  - ABANDONED"
      schema:
        type: string
    DestinationId:
      name: destination_id
      in: query
      description: 'Limit the list of videos to a single Social destination, by it''s ID. Note that this may conflict with `platform`, above. (e.g., Specifying `platform=YOUTUBE` and passing the ID of a Twitter destination will result in no statuses.)  Generally if you are passing a `destination_id` you probably don''t want to be passing a `platform` as well, as destinations imply a platform.

        '
      required: false
      schema:
        type: string
        format: uuid
    Since:
      name: since
      in: query
      description: Limit the list of videos to those whose last status change occurred since the specified date time.  Can accept either a full timestamp, or just a datestamp.  If passed just a datestamp, assumes 00:00:00 for the time, and the filter will be inclusive of the date specified.
      required: false
      schema:
        type: string
        format: date-time
  securitySchemes:
    BC_OAuth2:
      type: oauth2
      description: Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html) to learn more
      flows:
        clientCredentials:
          tokenUrl: https://oauth.brightcove.com/v4/access_token
          scopes:
            video-cloud/analytics/read: Read analytics data
            video-cloud/video/read: Read video data
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: https://backend_server