# Feedback

## List feedback for an agent

`client.agents.feedback.list(stringagentID, FeedbackListParamsparams, RequestOptionsoptions?): CursorPagination<ObjectiveFeedback>`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/feedback`

Lists feedback submitted across all objectives belonging to an agent. Supports search by comment, sentiment filter, agent variation filter, and creation date range. Results are ordered by creation time, newest first.

### Parameters

- `agentID: string`

- `params: FeedbackListParams`

  - `workspaceId: string`

    Path param

  - `agentVariationId?: string`

    Query param: Optional filter to limit results to feedback on objectives run by a single
    agent variation. Supports "external_id:" prefix for external IDs.

  - `createdAfter?: string`

    Query param: Inclusive lower bound on feedback creation time.

  - `createdBefore?: string`

    Query param: Exclusive upper bound on feedback creation time.

  - `cursor?: string`

    Query param: Pagination cursor from previous response.

  - `includeInfo?: boolean`

    Query param: When set to true you may use more of your alloted API rate-limit

  - `limit?: number`

    Query param: Maximum number of results to return.

  - `query?: string`

    Query param: Free-text search applied to the feedback comment. Case-insensitive substring match.

  - `sentiment?: "FEEDBACK_SENTIMENT_UNSPECIFIED" | "FEEDBACK_SENTIMENT_POSITIVE" | "FEEDBACK_SENTIMENT_NEGATIVE"`

    Query param: Filter by sentiment. UNSPECIFIED returns feedback regardless of score.

    - `"FEEDBACK_SENTIMENT_UNSPECIFIED"`

    - `"FEEDBACK_SENTIMENT_POSITIVE"`

    - `"FEEDBACK_SENTIMENT_NEGATIVE"`

### Returns

- `ObjectiveFeedback`

  ObjectiveFeedback represents feedback submitted for an objective's execution.
  Feedback is used to score agent variations and improve agent performance over time.

  - `data: ObjectiveFeedbackData`

    - `comment?: string`

      Optional human-readable comment explaining the feedback

    - `score?: number`

      A score between -1.0 and 1.0 representing the quality of the objective's execution.
      -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: string`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `accountId: string`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profileId: string`

      ID of the actor (user or service account) that created this operation

    - `workspaceId: string`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `externalId?: string`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels?: Record<string, string>`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `info?: ObjectiveFeedbackInfo`

    - `agentVariation?: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

      - `id?: string`

      - `name?: string`

        Human-readable name of the referenced resource, populated by the server
        on reads for convenience. Absent on references to resources that do not
        have a name (e.g., objective tasks).

    - `objective?: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

    - `submittedBy?: Profile`

      A profile identifies a user or non-human principal (such as an API key)
      at the account level. Profiles are account-scoped and can be granted access
      to multiple workspaces.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: string`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `accountId: string`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: string`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profileId: string`

        - `externalId?: string`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels?: Record<string, string>`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: "PROFILE_TYPE_UNSPECIFIED" | "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `"PROFILE_TYPE_UNSPECIFIED"`

          - `"PROFILE_TYPE_USER"`

          - `"PROFILE_TYPE_API_KEY"`

          - `"PROFILE_TYPE_SYSTEM"`

        - `email?: string`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name?: string`

          Display name (e.g., "Bobby Tables").

### Example

```typescript
import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const objectiveFeedback of client.agents.feedback.list('agentId', {
  workspaceId: 'workspaceId',
})) {
  console.log(objectiveFeedback.data);
}
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "comment": "comment",
        "score": 0
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "info": {
        "agentVariation": {
          "id": "id",
          "name": "name"
        },
        "objective": {
          "id": "id",
          "name": "name"
        },
        "submittedBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```