Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Gainsight connector

API Key CRM & SalesCustomer SupportAnalytics

Connect to Gainsight Customer Success to manage companies, contacts, calls to action, success plans, timeline activities, and custom objects. Power...

Gainsight connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “Set your credentials”

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Set up the connector

    Section titled “Set up the connector”

    Register your Gainsight credentials with Scalekit so it can authenticate requests on your behalf. You do this once per environment.

    Dashboard setup steps

    Register your Scalekit environment with the Gainsight connector so Scalekit can proxy API requests using your Gainsight access key. There is no redirect URI or OAuth flow.

    1. Generate a Gainsight access key

      • Sign in to Gainsight and go to Administration → Connectors 2.0 → Connections.
      • Click + Create Connection.
      • Select Gainsight API as the connector type, enter a connection name, and choose Access Key as the authentication type.
      • Click Generate Access Key.

      Gainsight Create Connection modal showing the Gainsight API connector type selected, a connection name field, Access Key authentication type selected, and the Generate Access Key button

    2. Create a connection in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Gainsight and click Create.
      • Note the Connection name — use this as connection_name in your code (e.g., gainsight).
      • Click Save.

    3. Add a connected account

      Via dashboard (for testing)

      • Open the connection and click the Connected Accounts tab → Add account.
      • Fill in:
        • Your User’s ID — a unique identifier for this user in your system (e.g., user_123)
        • Tenant Domain — your Gainsight hostname without https:// (e.g., mycompany.gainsightcloud.com)
        • Access Key — the key you generated in step 1
      • Click Save.

      Via API (for production)

      // Never hard-code API keys — read from secure storage or user input
      const gainsightKey = getUserGainsightKey(); // retrieve from your secure store
      

      await scalekit.actions.upsertConnectedAccount({
        connectionName: 'gainsight',
        identifier: 'user_123',
        credentials: {
          domain: 'mycompany.gainsightcloud.com',
          api_key: gainsightKey,
        },
      });

  4. Make your first call

    Section titled “Make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'gainsight'
    const identifier = 'user_123'
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'gainsight_company_query',
      toolInput: {},
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Update timeline, success plan, cta — Update one or more fields on an existing Timeline activity
  • Query timeline, scorecard, relationships — Search and filter Gainsight Timeline activity records by any field
  • Create timeline, task, cta — Log a new Timeline activity linked to a company in Gainsight
  • List task, success plan, object — List all tasks for a given CTA
  • User resolve — Look up Gainsight users by email or filter
  • Describe object — Return the full field schema for any Gainsight MDA object, including field names, types, and picklist values

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

gainsight_company_query # Search and filter Gainsight company records by any field. Returns up to 5000 records per call. 5 params

Search and filter Gainsight company records by any field. Returns up to 5000 records per call.

Name Type Required Description
limit integer optional Maximum number of records to return per call (1–5000). Default: 100.
offset integer optional Number of records to skip, used for pagination. Default: 0.
orderBy object optional Sort specification as an object with field names as keys and 'asc' or 'desc' as values. Custom fields use '__gc' suffix; lookup fields use '__gr'.
select array optional Field names to return. Omit to get standard fields (Name, Gsid, Status, Stage, ARR, etc.).
where object optional Filter object with conditions array and expression string. Each condition uses name (field name), alias, value array, and operator.
gainsight_cta_create # Create a Call to Action in Gainsight Cockpit linked to a company. Type, reason, status, and priority must match values configured in your Gainsight instance. 11 params

Create a Call to Action in Gainsight Cockpit linked to a company. Type, reason, status, and priority must match values configured in your Gainsight instance.

Name Type Required Description
company_gsid string required GSID of the company to link this record to. Retrieve it from gainsight_company_query.
cta_type string required CTA type as configured in your Gainsight instance, e.g. Risk, Expansion, Renewal. Check your Gainsight admin settings for valid values.
name string required Display name for this CTA, shown in the Gainsight Cockpit.
owner_email string required Email address of the Gainsight user to assign as owner. Resolved to an internal user ID automatically.
reference_id string required Your external identifier for this record, returned in error responses so you can match failures back to your source data.
comments string optional Free-text notes or context to attach to this CTA.
due_date string optional Due date in YYYY-MM-DD format.
playbook string optional Name of the playbook to apply. Must match a playbook configured in your Gainsight instance.
priority string optional Priority level for this record. Accepted values: High, Medium, Low.
reason string optional Reason name as configured in your Gainsight instance. Check your Gainsight admin settings for valid values.
status string optional Status value as configured in your Gainsight instance. Check your Gainsight admin settings for valid values.
gainsight_cta_list # Search and filter CTAs in Gainsight Cockpit with field selection and pagination. Returns up to 1000 CTAs per request. 5 params

Search and filter CTAs in Gainsight Cockpit with field selection and pagination. Returns up to 1000 CTAs per request.

Name Type Required Description
linkedObject boolean optional Set to true to include linked object data in the associatedRecords field of each CTA response.
pageNumber integer optional Page number to fetch, starting from 1. Default: 1.
pageSize integer optional Number of records per page (1–1000). Default: 50.
select array optional Field names to return. Custom fields must be appended with '__gc'; lookup fields with '__gr'. Omit to get standard CTA fields.
where object optional Filter object with conditions array and expression string. Each condition uses either fieldName (regular fields) or associatedRecord: true (linked object filter).
gainsight_cta_update # Update one or more fields on an existing CTA. Only the fields you include are changed — all other fields remain untouched. 10 params

Update one or more fields on an existing CTA. Only the fields you include are changed — all other fields remain untouched.

Name Type Required Description
gsid string required Gainsight internal ID (GSID) of the CTA to update. Retrieve it from gainsight_cta_list.
reference_id string required Your external identifier for this record, returned in error responses so you can match failures back to your source data.
comments string optional Free-text notes or context to attach to this CTA.
due_date string optional Due date in YYYY-MM-DD format.
is_closed boolean optional Set to true to mark this CTA as closed.
name string optional New display name for this CTA.
owner_email string optional Email address of the Gainsight user to assign as owner. Resolved to an internal user ID automatically.
priority string optional Priority level for this record. Accepted values: High, Medium, Low.
reason string optional Reason name as configured in your Gainsight instance. Check your Gainsight admin settings for valid values.
status string optional Status value as configured in your Gainsight instance. Check your Gainsight admin settings for valid values.
gainsight_object_describe # Return the full field schema for any Gainsight MDA object, including field names, types, and picklist values. Use gainsight_object_list to find valid object names. 5 params

Return the full field schema for any Gainsight MDA object, including field names, types, and picklist values. Use gainsight_object_list to find valid object names.

Name Type Required Description
object_name string required Gainsight MDA object name, e.g. Company, activity_timeline, call_to_action, or a custom object like MyObj__gc.
children_level integer optional Depth of child relationships to include when include_children is true. Default: 0.
include_children boolean optional Include child object relationships in the response. Default: false.
include_hidden_columns boolean optional Include hidden fields in the schema response. Default: false.
include_picklist_details boolean optional Include picklist option values in the response. Default: true.
gainsight_object_list # List all standard and custom objects available in Gainsight MDA. Use this to discover object names before calling gainsight_object_query or gainsight_object_describe. 2 params

List all standard and custom objects available in Gainsight MDA. Use this to discover object names before calling gainsight_object_query or gainsight_object_describe.

Name Type Required Description
em boolean optional Set to true to exclude related child objects from the results.
po string optional Filter to objects related to this parent object, e.g. company. Omit to return all objects.
gainsight_object_query # Query any standard or custom Gainsight MDA object by name. Custom objects use the __gc suffix (e.g. MyObject__gc). Use gainsight_object_list to discover available object names. 6 params

Query any standard or custom Gainsight MDA object by name. Custom objects use the __gc suffix (e.g. MyObject__gc). Use gainsight_object_list to discover available object names.

Name Type Required Description
object_name string required Gainsight MDA object name, e.g. Company, activity_timeline, call_to_action, or a custom object like MyObj__gc.
limit integer optional Maximum number of records to return per call (1–5000). Default: 100.
offset integer optional Number of records to skip, used for pagination. Default: 0.
orderBy object optional Sort specification as an object with field names as keys and 'asc' or 'desc' as values.
select array optional Field names to return. Custom fields end with '__gc'; lookup traversals use '__gr'. Omit for all fields.
where object optional Filter object with conditions array and expression string. Each condition uses name, alias, value array, and operator.
gainsight_query_company_person # Query contact-to-company associations in Gainsight. Each record links a person to a company with their role, title, and primary company designation. 5 params

Query contact-to-company associations in Gainsight. Each record links a person to a company with their role, title, and primary company designation.

Name Type Required Description
limit integer optional Maximum number of records to return per call (1–5000). Default: 100.
offset integer optional Number of records to skip, used for pagination. Default: 0.
orderBy object optional Sort specification as an object with field names as keys and 'asc' or 'desc' as values.
select array optional Field names to return. Key fields: Gsid, Person_ID, Company_ID, Active, IsPrimaryCompany, Role, Title, SfdcContactId, SfdcAccountId. Omit for standard fields.
where object optional Filter object with conditions array and expression string. Each condition uses name, alias, value array, and operator.
gainsight_query_relationships # Search and filter Gainsight relationship records by any field. Returns up to 5000 records per call. 5 params

Search and filter Gainsight relationship records by any field. Returns up to 5000 records per call.

Name Type Required Description
limit integer optional Maximum number of records to return per call (1–5000). Default: 100.
offset integer optional Number of records to skip, used for pagination. Default: 0.
orderBy object optional Sort specification as an object with field names as keys and 'asc' or 'desc' as values.
select array optional Field names to return, e.g. Name, Arr, Mrr. Omit for standard relationship fields.
where object optional Filter object with conditions array and expression string. Each condition uses name, alias, value array, and operator.
gainsight_query_scorecard # Query a Gainsight scorecard object for health score data. Pass the object name from your Gainsight configuration, e.g. cs_scorecard_master. 5 params

Query a Gainsight scorecard object for health score data. Pass the object name from your Gainsight configuration, e.g. cs_scorecard_master.

Name Type Required Description
scorecard_object string required Name of the scorecard object to query, e.g. cs_scorecard_master. Use gainsight_object_list to discover the exact name in your instance.
limit integer optional Maximum number of records to return per call (1–5000). Default: 100.
offset integer optional Number of records to skip, used for pagination. Default: 0.
select array optional Field names to return. Use gainsight_object_describe with the scorecard object name to discover available fields.
where object optional Filter object with conditions array and expression string.
gainsight_resolve_user # Look up Gainsight users by email or filter. Use this to find a user's GSID before assigning them as a CTA or success plan owner. 6 params

Look up Gainsight users by email or filter. Use this to find a user's GSID before assigning them as a CTA or success plan owner.

Name Type Required Description
email_search string optional Substring to match against user email addresses, case-insensitive. Useful for finding a user by partial email.
limit integer optional Maximum number of records to return per call (1–5000). Default: 50.
offset integer optional Number of records to skip, used for pagination. Default: 0.
orderBy object optional Sort specification as an object with field names as keys and 'asc' or 'desc' as values.
select array optional Field names to return. Key fields: Gsid, Name, Email, IsActive, Username, ExternalId. Omit for standard fields.
where object optional Filter object with conditions array and expression string. Each condition uses name, alias, value array, and operator.
gainsight_success_plan_list # Search and filter Success Plans in Gainsight with field selection and pagination. Returns up to 1000 records per request. 4 params

Search and filter Success Plans in Gainsight with field selection and pagination. Returns up to 1000 records per request.

Name Type Required Description
pageNumber integer optional Page number to fetch, starting from 1. Default: 1.
pageSize integer optional Number of records per page (1–1000). Default: 50.
select array optional Field names to return. Custom fields use '__gc' suffix; lookup fields use '__gr'. Omit to get standard Success Plan fields.
where object optional Filter object with conditions array and expression string. Each condition uses fieldName, alias, value array, and operator.
gainsight_success_plan_update # Update one or more fields on an existing success plan. Only the fields you include are changed — all other fields remain untouched. 7 params

Update one or more fields on an existing success plan. Only the fields you include are changed — all other fields remain untouched.

Name Type Required Description
plan_gsid string required GSID of the success plan to update. Retrieve it from gainsight_success_plan_list.
reference_id string required Your external identifier for this record, returned in error responses so you can match failures back to your source data.
due_date string optional Due date in YYYY-MM-DD format.
name string optional New display name for this success plan.
owner_email string optional Email address of the Gainsight user to assign as owner. Resolved to an internal user ID automatically.
status string optional Status value as configured in your Gainsight instance. Check your Gainsight admin settings for valid values.
templates array optional Names of templates to append to this success plan. Must match template names configured in your Gainsight instance.
gainsight_task_create # Create a task under an existing CTA in Gainsight Cockpit. The parent CTA must already exist — use gainsight_cta_list to get its GSID. 8 params

Create a task under an existing CTA in Gainsight Cockpit. The parent CTA must already exist — use gainsight_cta_list to get its GSID.

Name Type Required Description
cta_gsid string required GSID of the parent CTA this record belongs to. Retrieve it from gainsight_cta_list.
due_date string required Due date in YYYY-MM-DD format.
name string required Display name for this task, shown in Gainsight Cockpit.
owner_email string required Email address of the Gainsight user to assign as owner. Resolved to an internal user ID automatically.
reference_id string required Your external identifier for this record, returned in error responses so you can match failures back to your source data.
description string optional Optional free-text description providing additional context for this task.
priority string optional Priority level for this record. Accepted values: High, Medium, Low.
status string optional Status value as configured in your Gainsight instance. Check your Gainsight admin settings for valid values.
gainsight_task_list # List all tasks for a given CTA. Returns up to 1000 tasks per page. Use gainsight_cta_list to get the CTA's GSID. 4 params

List all tasks for a given CTA. Returns up to 1000 tasks per page. Use gainsight_cta_list to get the CTA's GSID.

Name Type Required Description
cta_gsid string required GSID of the parent CTA this record belongs to. Retrieve it from gainsight_cta_list.
includes string optional Comma-separated custom field API names to include beyond the default fields, e.g. DT_Date__gc,DT_DateTime__gc.
pn integer optional Page number to fetch, starting from 1. Default: 1.
ps integer optional Number of tasks per page (max 1000). Default: 1000.
gainsight_timeline_create # Log a new Timeline activity linked to a company in Gainsight. The external_id acts as an idempotency key — re-submitting the same value will not create a duplicate. 10 params

Log a new Timeline activity linked to a company in Gainsight. The external_id acts as an idempotency key — re-submitting the same value will not create a duplicate.

Name Type Required Description
activity_date string required Date and time of the activity in ISO 8601 format, e.g. 2024-01-15T10:30:00.000+0000.
author string required Email address of the Gainsight user authoring this activity. Must exist as an active user in your Gainsight instance.
company_gsid string required GSID of the company to link this record to. Retrieve it from gainsight_company_query.
external_id string required Unique ID from your system used as an idempotency key. Re-submitting the same ID will not create a duplicate activity.
notes string required Body text of the activity. Accepts plain text or HTML.
subject string required Title of the activity shown in the Timeline feed. Maximum 255 characters.
type_name string required Activity type as configured in your Gainsight instance, e.g. Meeting, Email, Phone Call.
context_name string optional The entity type this activity is attached to. Accepted values: Company, Relationship, CTA, SuccessPlan. Defaults to Company.
duration_mins integer optional Duration of the activity in minutes.
internal_attendees array optional List of internal Gainsight user emails attending this activity.
gainsight_timeline_query # Search and filter Gainsight Timeline activity records by any field. Returns up to 5000 records per call, sorted by creation date descending by default. 5 params

Search and filter Gainsight Timeline activity records by any field. Returns up to 5000 records per call, sorted by creation date descending by default.

Name Type Required Description
limit integer optional Maximum number of records to return per call (1–5000). Default: 50.
offset integer optional Number of records to skip, used for pagination. Default: 0.
orderBy object optional Sort specification as an object with field names as keys and 'asc' or 'desc' as values.
select array optional Field names to return. Custom fields use the format 'Prefix__FieldName__c'. Omit to get standard timeline fields.
where object optional Filter object with conditions array and expression string. Each condition uses name, alias, value array, and operator.
gainsight_timeline_update # Update one or more fields on an existing Timeline activity. Both activity_gsid and activity_type_id are required to identify the record. 7 params

Update one or more fields on an existing Timeline activity. Both activity_gsid and activity_type_id are required to identify the record.

Name Type Required Description
activity_gsid string required GSID of the Timeline activity to update. Returned as activityId in the gainsight_timeline_create response.
notes string required Body text of the activity. Accepts plain text or HTML.
subject string required Title of the activity shown in the Timeline feed. Maximum 255 characters.
activity_date string optional Date and time of the activity in ISO 8601 format, e.g. 2024-01-15T10:30:00.000+0000.
activity_type_id string optional GSID of the activity type. Required to identify the record type on update. Find it via gainsight_object_describe on the activity_timeline object.
company_name string optional Company name to re-link this activity to. Resolved to GsCompanyId automatically via lookup.
internal_attendees array optional Updated list of internal Gainsight user names attending this activity.