Documentation Index

Fetch the complete documentation index at: https://help.gong.io/llms.txt

Use this file to discover all available pages before exploring further.

List user's tasks (/v2/tasks)

  • Updated on Nov 17, 2025
  • Published on Oct 19, 2025
  • 5 minute(s) read
Prev Next
Post
/v2/tasks

Retrieves a list of Engage tasks assigned to a specific user, supporting filters for task type, action, and status. Results include detailed metadata for each task, such as ownership, creation and due dates, associated contacts, flows, accounts, and opportunities.

Required authorizaton scope: 'api:tasks:read'.

Body parameters
Expand All
object

Get user's tasks

userId
string Deprecated

The id of the Gong user who owns the task

Example234599484848423
workspaceId
string Deprecated

(Optional) The id of the workspace the tasks are in

Example623457276584334
filter
object (ReminderFilter) Required

Reminder filter criteria

userId
string Required

The id of the Gong user who owns the task

Example234599484848423
workspaceId
string

(Optional) The id of the workspace the tasks are in

Example623457276584334
types
Array of string Required

Defines whether to include tasks that were created as part of a flow, or were created as a one-off task

Example[ "MANUAL" ]
string
Valid values[ "FLOW", "MANUAL" ]
taskAction
Array of string Required

Array of actions included in the task (valid options: CALL)

Example[ "CALL" ]
string
Valid values[ "CALL" ]
status
Array of string Required

Only return tasks with this status (valid options: OPEN)

Example[ "OPEN" ]
string
Valid values[ "OPEN", "DONE", "DISMISSED" ]
Responses
200

Successful response

Expand All
object
requestId
string

A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.

Example4al018gzaztcr8nbukw
tasks
Array of object (ReminderDataDto)
object
id
integer (int64)

The id of the task

Example1234361284629351
userId
integer (int64)

The id of the Gong user who owns the task

Example234599484848423
created
string (date-time)

Date and time the task was created. In the ISO-8601 format (e.g., '2018-02-18T02:30:00-07:00' or '2018-02-18T08:00:00Z', where Z stands for UTC).

Example2018-02-17T10:30:00Z
updated
string (date-time)

Date and time the task was last updated. In the ISO-8601 format (e.g., '2018-02-18T02:30:00-07:00' or '2018-02-18T08:00:00Z', where Z stands for UTC).

Example2018-02-17T10:30:00Z
status
string

The task status

Valid values[ "OPEN", "DONE", "DISMISSED" ]
Example["OPEN"]
type
string

Describes whether the task was created as part of a flow, or is a one-off task.

Valid values[ "FLOW", "MANUAL" ]
Example["MANUAL"]
actions
Array of string

Action included in the task

Example[ "CALL" ]
string

Action included in the task

Valid values[ "CALL" ]
Example["CALL"]
account
object (AccountDto)

(Optional) associated crm account to task

crmId
string
name
string
crmUrl
string
crmEntityType
string Deprecated

This value is always ACCOUNT

Valid values[ "CONTACT", "CONTACT_WITHOUT_ACCOUNT", "LEAD", "LEAD_FIELD_HISTORY", "ACCOUNT", "OPPORTUNITY", "OPPORTUNITY_HISTORY", "OPPORTUNITY_FIELD_HISTORY", "ACCOUNT_FIELD_HISTORY", "CONTACT_FIELD_HISTORY", "OPPORTUNITY_STAGE", "USER", "TASK", "EVENT", "STAGE", "OPPORTUNITY_CONTACT_ROLE", "RECORD_TYPE", "NO_TYPE", "CAMPAIGN" ]
fields
Array of object (CrmFieldDto) Deprecated

Contains the same values as the fields of the object

object Deprecated

Contains the same values as the fields of the object

name
string
value
string
opportunity
object (OpportunityDto)

(Optional) associated crm deal to task

crmId
string
name
string
crmUrl
string
status
string
stage
string
amount
string
probability
string
closeDate
string
crmEntityType
string Deprecated

This value is always OPPORTUNITY

Valid values[ "CONTACT", "CONTACT_WITHOUT_ACCOUNT", "LEAD", "LEAD_FIELD_HISTORY", "ACCOUNT", "OPPORTUNITY", "OPPORTUNITY_HISTORY", "OPPORTUNITY_FIELD_HISTORY", "ACCOUNT_FIELD_HISTORY", "CONTACT_FIELD_HISTORY", "OPPORTUNITY_STAGE", "USER", "TASK", "EVENT", "STAGE", "OPPORTUNITY_CONTACT_ROLE", "RECORD_TYPE", "NO_TYPE", "CAMPAIGN" ]
fields
Array of object (CrmFieldDto) Deprecated

Contains the same values as the fields of the object

object Deprecated

Contains the same values as the fields of the object

name
string
value
string
dueDate
string (date-time)

Date and time the task is due to be completed in the ISO-8601 format (e.g., '2018-02-18T02:30:00-07:00' or '2018-02-18T08:00:00Z', where Z stands for UTC).

Example2018-02-17T10:30:00Z
flow
object (FlowDto)

(Optional) associated flow

id
integer (int64)

Flow id

Example1695493301223591000
name
string

Flow name

ExamplePersonal Flow
step
object (StepDto)
id
integer (int64)

Step id

Example1695493301223591000
name
string

Step name

ExampleMake a call
stepNumber
integer (int64)

Step number

Example1
contact
object (ContactDto)

(Optional) Array of additional contacts for the task

crmId
string

The contact's CRM id

Examplea5V1Q00A120DP4CVAW
type
string

Sets whether the contact is a lead or contact in the CRM

Valid values[ "CONTACT", "CONTACT_WITHOUT_ACCOUNT", "LEAD", "LEAD_FIELD_HISTORY", "ACCOUNT", "OPPORTUNITY", "OPPORTUNITY_HISTORY", "OPPORTUNITY_FIELD_HISTORY", "ACCOUNT_FIELD_HISTORY", "CONTACT_FIELD_HISTORY", "OPPORTUNITY_STAGE", "USER", "TASK", "EVENT", "STAGE", "OPPORTUNITY_CONTACT_ROLE", "RECORD_TYPE", "NO_TYPE", "CAMPAIGN" ]
ExampleLEAD
data
object (ContactCrmData)
firstName
string

The contact's first name

ExampleJon
lastName
string

The contact's last name

ExampleSnow
crmUrl
string

A link to the contact's page in the CRM

companyName
string

The name of the company the contact works for

ExampleGONG
affiliation
string

Contact affiliation

Valid values[ "Us", "Them", "Unknown" ]
ExampleUs
emails
Array of object (ContactEmailDto)
object
email
string

Email addresses associated with the contact

Exampletest@test.com
title
string

The contact's title

ExampleEnterprise Account Executive
timezone
string

(Optional) The timezone the contact lives in

ExampleUS/Pacific
phoneNumbers
Array of object (PersonPhoneDto)
object
raw
string
extension
string
countryCode
integer (int32)
normalized
string
label
string
isVerified
boolean
city
string

(Optional) The city the contact lives in

country
string

(Optional) The country the contact lives in

state
string

(Optional) The state the contact lives in

ExampleCalifornia
zipcode
string

(Optional) The contact's zipcode

optOutStatus
string Deprecated

(Optional) Whether the contact has opted out of being contacted

optOutChannels
Array of string

Contacts opted out channels

string
Valid values[ "CALLS", "EMAILS" ]
linkedinProfile
string

(Optional) A link to the contact's linkedIn profile

additionalContacts
Array of object (ContactDto)

(Optional) Array of additional contacts for the task

object

(Optional) Array of additional contacts for the task

crmId
string

The contact's CRM id

Examplea5V1Q00A120DP4CVAW
type
string

Sets whether the contact is a lead or contact in the CRM

Valid values[ "CONTACT", "CONTACT_WITHOUT_ACCOUNT", "LEAD", "LEAD_FIELD_HISTORY", "ACCOUNT", "OPPORTUNITY", "OPPORTUNITY_HISTORY", "OPPORTUNITY_FIELD_HISTORY", "ACCOUNT_FIELD_HISTORY", "CONTACT_FIELD_HISTORY", "OPPORTUNITY_STAGE", "USER", "TASK", "EVENT", "STAGE", "OPPORTUNITY_CONTACT_ROLE", "RECORD_TYPE", "NO_TYPE", "CAMPAIGN" ]
ExampleLEAD
data
object (ContactCrmData)
firstName
string

The contact's first name

ExampleJon
lastName
string

The contact's last name

ExampleSnow
crmUrl
string

A link to the contact's page in the CRM

companyName
string

The name of the company the contact works for

ExampleGONG
affiliation
string

Contact affiliation

Valid values[ "Us", "Them", "Unknown" ]
ExampleUs
emails
Array of object (ContactEmailDto)
object
email
string

Email addresses associated with the contact

Exampletest@test.com
title
string

The contact's title

ExampleEnterprise Account Executive
timezone
string

(Optional) The timezone the contact lives in

ExampleUS/Pacific
phoneNumbers
Array of object (PersonPhoneDto)
object
raw
string
extension
string
countryCode
integer (int32)
normalized
string
label
string
isVerified
boolean
city
string

(Optional) The city the contact lives in

country
string

(Optional) The country the contact lives in

state
string

(Optional) The state the contact lives in

ExampleCalifornia
zipcode
string

(Optional) The contact's zipcode

optOutStatus
string Deprecated

(Optional) Whether the contact has opted out of being contacted

optOutChannels
Array of string

Contacts opted out channels

string
Valid values[ "CALLS", "EMAILS" ]
linkedinProfile
string

(Optional) A link to the contact's linkedIn profile

title
string

The task title, only included if the task is of type MANUAL

400

Malformed request

object
requestId
string

A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.

Example4al018gzaztcr8nbukw
errors
Array of string

Error messages.

Example[ "An error has occurred" ]
string
403

Access denied

object
requestId
string

A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.

Example4al018gzaztcr8nbukw
errors
Array of string

Error messages.

Example[ "An error has occurred" ]
string
429

API request limit exceeded

Headers
Retry-After
integer
Number of seconds to wait before making a new request.
object
requestId
string

A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.

Example4al018gzaztcr8nbukw
errors
Array of string

Error messages.

Example[ "An error has occurred" ]
string
500

Failed to complete the operation due to an unexpected error

object
requestId
string

A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.

Example4al018gzaztcr8nbukw
errors
Array of string

Error messages.

Example[ "An error has occurred" ]
string