# Get a trigger’s fields

**GET** `/api/pieces/{id}/triggers/{triggerId}`

Returns one trigger’s fields, narrowed to the ones that apply for the values you pass.

Needs any [API token](https://docs.gorunner.io/api/authentication#scopes). No permission is checked.

## Parameters

### Path

- `id` · Required · string: The app’s id, as the trigger’s `pieceId` holds it.
- `triggerId` · Required · string: The trigger’s id: in a definition, the trigger’s `actionId`. A wrong one answers 404 naming the app’s triggers.

### Query

- `view` · Optional · string: Reserved. It narrows nothing.
- `version` · Optional · string: Reserved. It does nothing here: a trigger is answered at the default version.
- `gateValues` · Optional · object: Not sent as such: send any field of the trigger by its own name, such as `frequency=every_day`.

## Like an action, with two differences

It narrows as [Get an action’s fields](https://docs.gorunner.io/api/apps/get-app-action) does. `sideEffects` is always empty, and the trigger’s `type` is on the app, not here.

`sampleData` is the trigger’s stated example. For a form, a schedule or a callable trigger the real data depends on its settings: [get the sample](https://docs.gorunner.io/api/apps/get-trigger-sample) for those.

## Responses

- 200 OK

  The trigger, narrowed.

- 403 `FORBIDDEN`

  The token may not do this.

- 404 `NOT_FOUND`

  No such app, or the app has no such trigger: the message names the ones it has. An app this workspace may not use answers 404 too.

- 503 `PIECES_UNAVAILABLE`

  GoRunner couldn’t check which apps this workspace may use. Try again.

Any call can also answer: [`401 UNAUTHORIZED`](https://docs.gorunner.io/errors#UNAUTHORIZED) · [`401 TOKEN_ENDED`](https://docs.gorunner.io/errors#TOKEN_ENDED) · [`403 TOKEN_SURFACE_OFF`](https://docs.gorunner.io/errors#TOKEN_SURFACE_OFF) · [`403 FEATURE_OFF`](https://docs.gorunner.io/errors#FEATURE_OFF) · [`403 EMBED_NOT_ALLOWED`](https://docs.gorunner.io/errors#EMBED_NOT_ALLOWED) · [`403 EMBED_NOT_AVAILABLE`](https://docs.gorunner.io/errors#EMBED_NOT_AVAILABLE) · [`403 ACCOUNT_SUSPENDED`](https://docs.gorunner.io/errors#ACCOUNT_SUSPENDED) · [`429 RATE_LIMITED`](https://docs.gorunner.io/errors#RATE_LIMITED) · [`503 BUSY`](https://docs.gorunner.io/errors#BUSY) · [`503 PAUSED`](https://docs.gorunner.io/errors#PAUSED) · [`503 SERVICE_UNAVAILABLE`](https://docs.gorunner.io/errors#SERVICE_UNAVAILABLE). See [Errors](https://docs.gorunner.io/api/errors#by-status).

Request

**curl**

```bash
GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs any API token
APP_ID="schedule"
TRIGGER_ID="schedule"

URL="$GORUNNER/api/pieces/$APP_ID/triggers/"
URL="${URL}$TRIGGER_ID?frequency=every_day"
curl "$URL" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"
```

**JavaScript**

```js
const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const APP_ID = process.env.APP_ID;
const TRIGGER_ID = process.env.TRIGGER_ID;

const res = await fetch(
  `${GORUNNER}/api/pieces/${APP_ID}/triggers/` +
    `${TRIGGER_ID}?frequency=every_day`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();
```

**Python**

```python
import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
APP_ID = os.environ["APP_ID"]
TRIGGER_ID = os.environ["TRIGGER_ID"]

res = requests.get(
    f"{GORUNNER}/api/pieces/{APP_ID}/triggers/"
    f"{TRIGGER_ID}",
    params={"frequency": "every_day"},
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]
```

Response · 200 OK, shortened

```json
{
  "data": {
    "pieceId": "schedule",
    "pieceVersion": "1.0.0",
    "id": "schedule",
    "name": "Schedule",
    "inputSchema": {
      "type": "object",
      "properties": {
        "frequency": {
          "type": "string"
        },
        "hour_of_the_day": {
          "type": "string"
        },
        "run_on_weekends": {
          "type": "boolean"
        },
        "timezone": {
          "type": "string"
        }
      }
    },
    "sampleData": {},
    "filteredBy": {
      "frequency": "every_day"
    }
  }
}
```

**Every field**

It takes no body.

### Response · 200 OK

- `data` · object: One action or trigger with its schema, narrowed to the fields that apply given the gate values supplied in the query string.
  - `pieceId` · string
  - `pieceVersion` · string: The app’s default version — what a new step referencing this operation will be pinned to.
  - `id` · string: The operation id: a step’s `actionId`, or a trigger’s `actionId`.
  - `name` · string
  - `description` · string
  - `sideEffects` · string: Actions only; always empty on the trigger endpoint. One of `pure`, `reads_external`, `writes_external`.
  - `inputSchema` · object: A schema as the projections serve it: presentation fields removed, properties possibly narrowed.
    - `type` · string
    - `properties` · object
      - `{key}` · object: One property as the projections serve it: everything that constrains a legal value, nothing about screen layout (`title`, `order`, `placeholder` and `group` are dropped — 11.8% of the payload). Recursive through `properties` and `items`. Each key’s value.
        - `type` · string
        - `description` · string: The field’s whole help for whoever writes it: the step panel’s text, then the notes for an agent (`agentNotes` in the full schema).
        - `default`: Default value, of any JSON type.
        - `enum` · array of strings: Closed set of legal values.
        - `enumLabels` · object: Display labels; omitted entirely when they are identical to the enum values.
          - `{key}` · string: Each key’s value.
        - `format` · string
        - `properties` · object
          - `{key}` · object: One property as the projections serve it: everything that constrains a legal value, nothing about screen layout (`title`, `order`, `placeholder` and `group` are dropped — 11.8% of the payload). Recursive through `properties` and `items`. The same fields as `data.inputSchema.properties.{key}` above.
        - `items` · object: One property as the projections serve it: everything that constrains a legal value, nothing about screen layout (`title`, `order`, `placeholder` and `group` are dropped — 11.8% of the payload). Recursive through `properties` and `items`. The same fields as `data.inputSchema.properties.{key}` above.
        - `propertyType` · string: How the value is chosen. DROPDOWN / MULTI_SELECT / DYNAMIC mean the options come from the app at run time — see `dynamicFields`.
        - `required` · boolean: The per-property requiredness flag. The schema-level `required` array is authoritative for the narrowed view.
        - `minLength` · integer
        - `maxLength` · integer
        - `min` · number
        - `max` · number
        - `pattern` · string
        - `refreshers` · array of strings
        - `language` · string
        - `displayConditions` · array of objects: Kept deliberately: a field marked conditional must show WHAT would decide it.
          - `field` · string: The sibling property whose value decides this one. Every gate field is itself a property of the same schema, so its declared type and enum are the legal values.
          - `operator` · string: An unrecognized operator is treated permissively (the property is kept). One of `eq`, `neq`, `in`, `notIn`, `contains_any`, `exists`, `notExists`.
          - `value`: Comparison value for eq/neq, of any scalar JSON type.
          - `values` · array: Candidate list for in / notIn / contains_any.
        - `bound` · boolean: The value, though typed as text, points into the connected account (a spreadsheet, a calendar, a folder, a label): it means nothing to another account, so a template used outside the workspace it was saved in arrives with it blank. Absent when false.
        - `noExpressions` · boolean: True when `{{ }}` is NOT replaced in this field: the value is used exactly as written (Code 2.0.0’s `code`, where values come from `inputs`, `steps` and `trigger` instead). Never write an expression into such a field.
    - `required` · array of strings: Always present (possibly empty). Excludes every field listed in `conditionalFields`.
  - `outputSchema` · object: A schema as the projections serve it: presentation fields removed, properties possibly narrowed. The same fields as `data.inputSchema` above.
  - `sampleData` · object: Declared example output (for a trigger, the declared `{{trigger.*}}` shape).
  - `filteredBy` · object: The gate values that were ACTUALLY applied — the raw query intersected with the fields this operation is really gated on. If a parameter you sent is missing here, it narrowed nothing. Absent when nothing narrowed.
    - `{key}` · string: Each key’s value.
  - `ignored` · array of strings: Query keys that gate nothing on this operation — a misspelling (`bodyType` for `body_type`), or a gate belonging to a different operation. Fix these rather than believing the filter worked. Absent when empty.
  - `unresolved` · array of strings: Gate fields the SURVIVING properties still depend on and which you did not supply. Adding these as query parameters narrows the schema further.
  - `conditionalFields` · array of strings: Fields kept ONLY because their gate was left undecided. They are deliberately excluded from `required` even when the app declares them required — supply their gate to find out whether they really apply.
  - `dynamicFields` · array of strings: Properties whose legal values are not in this schema. Fetch them from POST /api/pieces/{id}/actions/{actionId}/options/{propertyName}.

Related: [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) · [Get an app](https://docs.gorunner.io/api/apps/get-app) · [Triggers](https://docs.gorunner.io/build/triggers)

Source: https://docs.gorunner.io/api/apps/get-app-trigger