Overview

Codeium supports an API for custom analytics in version. It allows querying for data from autocomplete, chat, and command, and a variety of filters, groupings, and aggregations. This article is for the SaaS version of codeium; see this article for the on-prem version.

Analytics API specification

We provide examples in curl; it can then be translated into HTTP requests in other languages.

curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "<SERVICE_KEY>",
  "group_name": "<GROUP_NAME>",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_<DATA_SOURCE>",
      "selections": [
        <LIST OF SELECTIONS>
      ],
      "filters": [
        <LIST OF FILTERS>
      ],
      "aggregations": [
        <LIST OF AGGREGATIONS>
      ],
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics

DATA_SOURCE: select either USER_DATA, CHAT_DATA, or COMMAND_DATA depending on whether you are looking for autocomplete, chat, or command data.

SERVICE_KEY: The service key - an admin user can create a new one from https://codeium.com/team/team_settings

GROUP_NAME: The name of a group to filter on. This field is optional.

Schemas for selections, filters, aggregations, and orderings are in the following section, in JSON format. Example queries and for each of the three data sources, as well as query debugging tips, will be at the end of the document.

Schemas

Selections

Selections are required. Each selection corresponds to a value to be queried.

{
  "field": "<FIELD_NAME>",
  "name": "<NAME>",
  "aggregation_function": "QUERY_AGGREGATION_<AGGREGATION_FUNCTION>"
}

FIELD_NAME: The field you wish to query. See the Available Fields section below.

NAME: An alias for the field. If not specified, will be the lowercase version of <AGGREGATION_FUNCTION>_<FIELD_NAME>, e.g. sum_num_acceptances. Must be distinct from all other field and aggregation names.

AGGREGATION_FUNCTION: should be one of UNSPECIFIED, COUNT, SUM, AVG, MAX, MIN. If "aggregation_function" is not provided, defaults to UNSPECIFIED.

Filters

Filters are used to narrow down the data to only contain elements that meet certain criteria. They are optional.

{
  "name": "<NAME>",
  "value": "<VALUE>",
  "filter": "QUERY_FILTER_<FILTER>"
}

NAME: The name of the field you wish to filter. If the filtered item is the same as a Selection/Aggregation, this must be equal to the name of the field/aggregation.

VALUE: the value being compared.

FILTER: One of EQUAL, NOT_EQUAL, GREATER_THAN, LESS_THAN, GE (greater than or equal), LE (less than or equal).

Aggregations

Aggregations are used to split the data into groups based off a specified criteria. They are optional.

{
  "field": <FIELD_NAME>,
  "name": <NAME>
}

FIELD_NAME: The field you wish to query. See the Available Fields section.

NAME: An alias for the field. Must be distinct from all other field and aggregation names.

Available Fields

User Data

All data from the USER_DATA source is aggregated per user, per hour.

Chat Data

Note that all data provided in the chat data API are for the chat model responses, not the user questions.

Command Data

Note that the Command Data source contains all commands, including those which were declined. The "accepted" field can be used to filter for only accepted commands.

Examples

User Data

curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": SERVICE_KEY,
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "pcw",
          "name": "pcw"
        }
      ],
      "filters": [
        {
          "name": "hour",
          "filter": "QUERY_FILTER_GE",
          "value": "2024-01-01"
        },
        {
          "name": "hour",
          "filter": "QUERY_FILTER_LE",
          "value": "2024-02-01"
        }
      ]
    }
  ]
}' \
https://<ENTERPRISE_PORTAL_URL>/api/v1/Analytics

This query calculates the overall Percent Code Written over the month of January 2024. Example response (JSON formatted for readability):

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            pcw: 0.45
          }
        }
      ]
    }
  ]
}

Chat Data

curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": SERVICE_KEY,
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_CHAT_DATA",
      "selections": [
        {
          "field": "chat_loc_used",
          "name": "chat_loc_used",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "latest_intent_type",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "CHAT_INTENT_FUNCTION_DOCSTRING"
        }
      ],
      "aggregations": [
        {
          "field": "ide",
          "name": "ide"
        }
      ]
    }
  ]
}' \
https://<ENTERPRISE_PORTAL_URL>/api/v1/Analytics

This query shows the number of lines of code accepted from the "Generate Docstring" code lens, for all time, grouped by IDE.

Example response:

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "chat_loc_used": "74",
            "ide": "jetbrains"
          },
        },
        {
          "item": {
            "chat_loc_used":"41",
            "ide":"vscode"
          },
        }
      ]
    }
  ]
}

Command Data

curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": SERVICE_KEY,
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_COMMAND_DATA",
      "selections": [
        {
          "field": "lines_added",
          "name": "lines_added",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        },
        {
          "field": "lines_removed",
          "name": "lines_removed",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "provider_source",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "PROVIDER_SOURCE_COMMAND_EDIT"
        },
        {
          "name": "accepted",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "true"
        }
      ],
      "aggregations": [
        {
          "field": "language",
          "name": "language"
        }
      ]
    }
  ]
}' \
https://<ENTERPRISE_PORTAL_URL>/api/v1/Analytics

This query gets the number of lines added and removed from "edit" commands, grouped by programming language.

Example response:

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "language": "SHELL",
            "lines_added": "5",
            "lines_removed": "3"
          }
        },
        {
          "item": {
            "language": "GO",
            "lines_added": "31",
            "lines_removed": "27"
          }
        },
        {
          "item": {
            "language": "PYTHON",
            "lines_added": "21",
            "lines_removed": "5"
          }
        },
        {
          "item": {
            "language": "UNSPECIFIED",
            "lines_added": "91",
            "lines_removed": "71"
          }
        },
        {
          "item": {
            "language": "STARLARK",
            "lines_added": "13",
            "lines_removed": "1"
          }
        }
      ]
    }
  ]
}

Query debugging

From 1.10.0 and on, invalid queries will return an error message. This section has some common error messages, what they mean, and how to debug the corresponding queries.

"selections": [
  {
    "field": "num_acceptances",
    "name": "total_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "name": "total_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
  }
]

"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]

"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]