Arkestro event analytics API

openapi: 3.2.0
info:
  version: '2.0'
  title: V2 event analytics API
  description: 'The Arkestro API is used to manage aspects of your Arkestro instance without needing to have a user session.

    Our current API offering features endpoints that allow the creation and execution of an event.


    To get started, please generate an API Token.

    To generate an API Token your user must be an admin and you must request the feature be made available.

    Once enabled, you can go to your User Settings -> Personal Access Tokens and generate a new API token.  This API token will be used in your request

    header as an X-Token.


    Once you have an API Token you can make your first request.  A good starting point would be to request one of the index endpoints, such as:

    curl --location --request GET ''https://api.arkestro.com/api/v2/events'' --header ''Accept: application/json'' --header ''X-Token: <YOUR API TOKEN>'''
servers:
- url: https://api.arkestro.com
security:
- ApiKeyAuth: []
tags:
- name: event analytics
paths:
  /api/v2/event_analytics/metrics/export_task:
    post:
      summary: Metrics
      tags:
      - event analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                export_task:
                  type: object
                  required:
                  - callback_url
                  - callback_action
                  properties:
                    callback_url:
                      type: string
                      description: The URL to return a presigned url to
                    callback_action:
                      type: string
                      description: The action the URL takes, POST, GET, PATCH, etc.
                additionalProperties: false
              additionalProperties: false
            example:
              export_task:
                callback_url: https://callback.com
                callback_action: post
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  export_task:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: The ID of the job that is building the export
                additionalProperties: false
              example:
                export_job_id: 123
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
  /api/v2/event_analytics/rounds/export_task:
    post:
      summary: Rounds
      tags:
      - event analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                export_task:
                  type: object
                  required:
                  - callback_url
                  - callback_action
                  properties:
                    callback_url:
                      type: string
                      description: The URL to return a presigned url to
                    callback_action:
                      type: string
                      description: The action the URL takes, POST, GET, PATCH, etc.
                additionalProperties: false
              additionalProperties: false
            example:
              export_task:
                callback_url: https://callback.com
                callback_action: post
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  export_task:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: The ID of the job that is building the export
                additionalProperties: false
              example:
                export_task:
                  id: 123
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
  /api/v2/event_analytics/buyer_leaderboards:
    get:
      summary: Buyer Leaderboards
      tags:
      - event analytics
      description: Retrieve buyer leaderboards data
      parameters:
      - name: business_unit_id
        in: query
        description: 'One or more business unit IDs to filter by. Accepts multiple values. Pass them as repeated query params: `?business_unit_id[]=1&business_unit_id[]=2`.

          '
        required: false
        schema:
          type: integer
      - name: creator_user_full_name
        in: query
        description: One or more full names (first + last) of the user who created the resource. Accepts multiple values. Pass them as repeated query params `?creator_user_full_name[]=John%20Doe&creator_user_full_name[]=Jane%20Smith`. Please note, URL encoding may be handled automatically depending on your language.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of items to return. Defaults to `1`, Max `1000`.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 10
      - name: offset
        in: query
        description: The number of results to skip before starting to collect the result set. Defaults to `0`.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: sort_by
        in: query
        description: The field to sort the items by which can be any value from the data field.
        required: false
        schema:
          type: string
          default: business_leaderboard_id
      - name: sort_order
        in: query
        description: The sorting order (`asc` for ascending, `desc` for descending). Defaults to `asc`.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - company_id
                - business_unit_id
                - dbt_run_id
                - dbt_run_ts
                - last_updated_at
                properties:
                  business_unit_id:
                    type: array
                    items:
                      type: integer
                    description: Arkestro business unit ID used for filtering the results.
                  company_id:
                    type: integer
                    description: Arkestro company ID used for filtering the results.
                  creator_full_name:
                    type: array
                    items:
                      type: string
                    description: Full name of the user who created the events used for filtering the results.
                  data:
                    type: array
                    description: Array of buyer leaderboard records.
                    items:
                      type: object
                      properties:
                        baseline_total:
                          type: number
                          format: float
                          description: Sum of baseline amounts (company preferred currency) across all time in scope.
                        baseline_total_28d:
                          type: number
                          format: float
                          description: Sum of baseline (preferred currency) for the last 28 days.
                        baseline_total_90d:
                          type: number
                          format: float
                          description: Sum of baseline (preferred currency) for the last 90 days.
                        baseline_total_prev_28d:
                          type: number
                          format: float
                          description: Sum of baseline (preferred currency) for the time window between 28 and 48 days ago.
                        baseline_total_prev_90d:
                          type: number
                          format: float
                          description: Sum of baseline (preferred currency) for the time window between 90 and 180 days ago.
                        baseline_trend_28d:
                          type: number
                          format: float
                          description: Baseline growth vs. the time window between 28 and 48 days ago, ratio (curr-prev)/prev.
                        baseline_trend_90d:
                          type: number
                          format: float
                          description: Baseline growth vs. the time window between 90 and 180 days ago, ratio (curr-prev)/prev.
                        business_unit_id:
                          type: integer
                          description: Unique identifier of the business unit.
                        business_unit_name:
                          type: string
                          description: Business unit name.
                        buyer_leaderboard_id:
                          type: string
                          description: Deterministic surrogate key for the buyer leaderboard row (hash of company_id, company_name, business_unit_name, creator_user_full_name).
                        company_id:
                          type: integer
                          description: Buyer company ID.
                        company_name:
                          type: string
                          description: Buyer company name.
                        creator_user_full_name:
                          type: string
                          description: Full name of the buyer who created the event (e.g. John Doe).
                        dbt_run_id:
                          type: string
                          description: dbt invocation_id for the run that produced this row.
                        dbt_run_ts:
                          type: string
                          format: date-time
                          description: Timestamp when the dbt run started.
                        event_count:
                          type: integer
                          description: Total distinct events for this buyer across all time.
                        event_count_28d:
                          type: integer
                          description: Distinct events opened in the the last 28 days.
                        event_count_90d:
                          type: integer
                          description: Distinct events opened in the last 90 days.
                        event_count_prev_28d:
                          type: integer
                          description: Distinct events opened in the window between 28 and 48 days ago.
                        event_count_prev_90d:
                          type: integer
                          description: Distinct events opened in the the window between 90 and 180 days ago.
                        event_count_trend_90d:
                          type: number
                          format: float
                          description: Event openings growth vs. the time window between 90 and 180 days ago, ratio (curr-prev)/prev.
                        events_opened_trend:
                          type: number
                          format: float
                          description: Event openings change between the last 28 day time window and the prior 28-48 day time window. Calculated as (current-prior)/prior.
                        item_count:
                          type: integer
                          description: Total distinct line items for this buyer across all time.
                        item_count_28d:
                          type: integer
                          description: Total distinct line items in the last 28 days.
                        item_count_90d:
                          type: integer
                          description: Total distinct line items in the last 90 days.
                        item_count_prev_90d:
                          type: integer
                          description: Total distinct line items in the time window between 90 and 180 days ago.
                        item_count_with_baseline_anomaly:
                          type: integer
                          description: Total number of line items with a baseline anomaly.
                        item_count_with_baseline_anomaly_28d:
                          type: integer
                          description: Line items with a baseline anomaly in the last 28 days.
                        item_count_with_baseline_anomaly_90d:
                          type: integer
                          description: Line items with a baseline anomaly in the last 90 days.
                        item_count_with_quote_anomaly:
                          type: integer
                          description: Total number of line items with a quote anomaly.
                        item_count_with_quote_anomaly_28d:
                          type: integer
                          description: Line items with a quote anomaly in the last 28 days.
                        item_count_with_quote_anomaly_90d:
                          type: integer
                          description: Line items with a quote anomaly in the last 90 days.
                        item_win_count_90d:
                          type: integer
                          description: Total distinct winning line items (non-negative savings) in the last 90 days.
                        item_win_count_prev_90d:
                          type: integer
                          description: Total distinct winning line items (non-negative savings) in the time window between 90 and 180 days ago.
                        potential_savings_in_pref_currency:
                          type: number
                          format: float
                          description: Sum of potential savings (company preferred currency) across all time in scope. Potential savings is (baseline - lowest quote amount) * requested quantity of units.
                        potential_savings_in_pref_currency_28d:
                          type: number
                          format: float
                          description: Sum of potential savings (preferred currency) in the last 28 days.
                        potential_savings_in_pref_currency_90d:
                          type: number
                          format: float
                          description: Sum of potential savings (preferred currency) in the last 90 days.
                        potential_savings_in_pref_currency_prev_28d:
                          type: number
                          format: float
                          description: Sum of potential savings (preferred currency) in the time window between 28 and 48 days ago.
                        potential_savings_in_pref_currency_prev_90d:
                          type: number
                          format: float
                          description: Sum of potential savings (preferred currency) in the time window between 90 and 180 days ago.
                        potential_savings_percent:
                          type: number
                          format: float
                          description: Overall potential savings percent. Computed as SUM(potential_savings)/SUM(baseline_total where we have a baseline and quote). Please note that this is NULL if we do not have quotes or a baseline and it can be negative.
                        potential_savings_trend_28d:
                          type: number
                          format: float
                          description: Potential savings growth vs. the time window between 28 and 48 days ago, ratio (curr-prev)/prev.
                        potential_savings_trend_90d:
                          type: number
                          format: float
                          description: Potential savings growth vs. the time window between 90 and 180 days ago, ratio (curr-prev)/prev.
                        supplier_engagement:
                          type: number
                          format: float
                          description: 'Overall supplier engagement score, percent 0 to 100 (rounded). Computed as SUM(engagement_score_total)/SUM(engagement_opportunity_total)*100. The opportunities include tasks such as submitting a quote, accepting the suggested price, viewing the event, completing a survey, uploading documents, and replying to messages.

                            '
                        supplier_engagement_28d:
                          type: number
                          format: float
                          description: Supplier engagement score in the last 28 days, ratio 0 to 1 (not percent).
                        supplier_engagement_90d:
                          type: number
                          format: float
                          description: Supplier engagement score in the last 90 days, ratio 0 to 1 (not percent).
                        supplier_engagement_prev_28d:
                          type: number
                          format: float
                          description: supplier engagement score in the time window between 28 and 48 days ago, ratio 0 to 1 (not percent).
                        supplier_engagement_prev_90d:
                          type: number
                          format: float
                          description: supplier engagement score in the time window between 90 and 180 days ago, ratio 0 to 1 (not percent).
                        supplier_engagement_trend:
                          type: number
                          format: float
                          description: Engagement growth change between the last 28 day time window and the prior 28-48 day time window. Calculated as (curr-prev)/prev.
                        supplier_engagement_trend_90d:
                          type: number
                          format: float
                          description: Engagement growth vs. the time window between 90 and 180 days ago, ratio (curr-prev)/prev.
                        win_rate_percent_28d:
                          type: number
                          format: float
                          description: Win rate in the last 28 days. A win is if the potential savings is non-negative for the line item.
                        win_rate_percent_90d:
                          type: number
                          format: float
                          description: Win rate in the last 90 days, ratio 0 to 1 (not percent).
                        win_rate_percent_prev_28d:
                          type: number
                          format: float
                          description: Win rate in the time window between 28 and 48 days ago.
                        win_rate_percent_prev_90d:
                          type: number
                          format: float
                          description: Win rate in the time window between 90 and 180 days ago, ratio 0 to 1 (not percent).
                        win_rate_text:
                          type: string
                          description: 'Overall win ratio formatted as "wins / items (P%)" where P is the overall win percentage, rounded. A win is if the potential savings is non-negative for the line item.

                            '
                        win_rate_text_28d:
                          type: string
                          description: Win ratio for the last 28 days formatted "wins / items (percent)". Wins are the count of line items with non-negative potential savings.
                        win_rate_text_90d:
                          type: string
                          description: Win ratio for the last 90 days formatted "wins / item (percent)". Wins are the count of line items with non-negative potential savings.
                        win_rate_text_prev_28d:
                          type: string
                          description: Win ratio for the time window between 28 and 48 days ago formatted "wins / items (percent)". Wins are the count of line items with non-negative potential savings.
                        win_rate_text_prev_90d:
                          type: string
                          description: Win ratio for the time window between 90 and 180 days ago formatted "wins / item (percent)". Wins are the count of line items with non-negative potential savings.
                        win_rate_trend_28d:
                          type: number
                          format: float
                          description: Win rate growth change between the last 28 day time window and the prior 28-48 day time window. Calculated as (curr-prev)/prev.
                        win_rate_trend_90d:
                          type: number
                          format: float
                          description: Win rate growth vs. the time window between 90 and 180 days ago, ratio (curr-prev)/prev.
                  limit:
                    type: integer
                    description: Maximum number of records returned in the page.
                  offset:
                    type: integer
                    description: Offset of the first record in the returned page.
                  sort_by:
                    type: string
                    description: Field used for sorting the results.
                  sort_order:
                    type: string
                    description: Sort order, either 'asc' or 'desc'.
              example:
                business_unit_id:
                - '1'
                company_id: 1
                creator_full_name: null
                data:
                - baseline_total: 0.0
                  baseline_total_28d: 0.0
                  baseline_total_90d: 0.0
                  baseline_total_prev_28d: 0.0
                  baseline_total_prev_90d: 0.0
                  baseline_trend_28d: 0.0
                  baseline_trend_90d: 0.0
                  business_unit_id: 1
                  business_unit_name: Default
                  buyer_leaderboard_id: f624fd41ecd7cd38744db47848bb8110
                  company_id: 1
                  company_name: Akrestro
                  creator_user_full_name: louis boo
                  dbt_run_id: 40181b4f-ac1d-448e-bf2d-146517f56eaf
                  dbt_run_ts: '2025-09-03 08:15:07.203375+00:00'
                  event_count: 1
                  event_count_28d: 1
                  event_count_90d: 1
                  event_count_prev_28d: 0
                  event_count_prev_90d: 0
                  event_count_trend_90d: 0.0
                  events_opened_trend: 0.0
                  item_count: 3
                  item_count_28d: 3
                  item_count_90d: 3
                  item_count_prev_90d: 0
                  item_count_with_baseline_anomaly: 0
                  item_count_with_baseline_anomaly_28d: 0
                  item_count_with_baseline_anomaly_90d: 0
                  item_count_with_quote_anomaly: 0
                  item_count_with_quote_anomaly_28d: 0
                  item_count_with_quote_anomaly_90d: 0
                  item_win_count_90d: 0
                  item_win_count_prev_90d: 0
                  potential_savings_in_pref_currency: null
                  potential_savings_in_pref_currency_28d: 0.0
                  potential_savings_in_pref_currency_90d: 0.0
                  potential_savings_in_pref_currency_prev_28d: 0.0
                  potential_savings_in_pref_currency_prev_90d: 0.0
                  potential_savings_percent: null
                  potential_savings_trend_28d: 0.0
                  potential_savings_trend_90d: 0.0
                  supplier_engagement: 0.0
                  supplier_engagement_28d: 0.0
                  supplier_engagement_90d: 0.0
                  supplier_engagement_prev_28d: 0.0
                  supplier_engagement_prev_90d: 0.0
                  supplier_engagement_trend: 0.0
                  supplier_engagement_trend_90d: 0.0
                  win_rate_percent_28d: 0.0
                  win_rate_percent_90d: 0.0
                  win_rate_percent_prev_28d: 0.0
                  win_rate_percent_prev_90d: 0.0
                  win_rate_text: 0 / 3 (0%)
                  win_rate_text_28d: 0 / 3
                  win_rate_text_90d: 0 / 3
                  win_rate_text_prev_28d: 0 / 0
                  win_rate_text_prev_90d: 0 / 0
                  win_rate_trend_28d: 0.0
                  win_rate_trend_90d: 0.0
                limit: 1
                offset: 1
                sort_by: potential_savings_percent
                sort_order: desc
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
  /api/v2/event_analytics/quotes:
    get:
      summary: Quotes
      tags:
      - event analytics
      description: Retrieve quotes data
      parameters:
      - name: business_unit_id
        in: query
        description: 'One or more business unit IDs to filter by. Accepts multiple values. Pass them as repeated query params: `?business_unit_id[]=1&business_unit_id[]=2`.

          '
        required: false
        schema:
          type: integer
      - name: start_date
        in: query
        description: The start date to filter events by, in ISO 8601 format (YYYY-MM-DD).
        required: false
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: The end date to filter events by, in ISO 8601 format (YYYY-MM-DD).
        required: false
        schema:
          type: string
          format: date
      - name: owner_full_name
        in: query
        description: One or more full names (first + last) of the user who owns the event. Accepts multiple values. Pass them as repeated query params `?owner_full_name[]=John%20Doe&owner_full_name[]=Jane%20Smith`. Please note, URL encoding may be handled automatically depending on your language.
        required: false
        schema:
          type: string
      - name: supplier_org_name
        in: query
        description: One or more names of the organizations supplying the resource. Accepts multiple values. Pass them as repeated query params `?supplier_org_name[]=Acme 20Corp&supplier_org_name[]=Globex 20Corp`.
        required: false
        schema:
          type: string
      - name: event_state
        in: query
        description: 'The state of the event (e.g., `draft`). Accepts multiple values. Pass them either as repeated query params: `?event_state[]=draft&event_state[]=awarded`.

          '
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - awarded
            - closed
            - draft
            - not_awarded
            - open_for_bidding
            - ready_to_award
        style: form
        explode: true
      - name: event_tag_names
        in: query
        description: 'AND filter — only events that have ALL specified tags are returned. Accepts multiple values. Pass them as repeated query params: `?event_tag_names[]=tag1&event_tag_names[]=tag2`.

          '
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: refreshed_after
        in: query
        description: The date and time after which the resource was last refreshed, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
        required: false
        schema:
          type: string
          format: date-time
      - name: offset
        in: query
        description: The number of results to skip before starting to collect the result set. Defaults to `0`.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        description: The maximum number of items to return. Defaults to `1`, Max `1000`.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 10

# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arkestro/refs/heads/main/openapi/arkestro-event-analytics-api-openapi.yml