> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List a monitor's firings

> Page through the occurrences a monitor has fired for, and how each delivery went

export const MonitorsExperimental = () => <Warning>
    <strong>Monitors is experimental.</strong> Request and payload shapes can change without a deprecation window. Monitors isn't recommended for production workflows.
  </Warning>;

<MonitorsExperimental />

## Notes

* To authenticate, you'll need a [Tako API key](https://tako.com/console/api-keys). It's best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
* Returns firings newest first. `limit` is 1–100 and defaults to 20. To get the next page, pass a response's `next_cursor` back as `cursor`.
* `occurred_at` is when the occurrence happened, and `fired_at` is when Tako fired for it. The gap between them is however long the source took to report the occurrence. For each type's reporting delay, see its `description` in [List monitor types](/api-reference/monitor-types).
* `occurrence_key` is what Tako deduplicates on. Tako records one firing per key, so a source that reposts the same occurrence doesn't fire twice.
* `payload` holds the values that caused the firing. Tako sends the same object to your channels under `payload`, and its fields depend on the monitor type. For the fields each type sends, see [Webhook deliveries](/documentation/integrating-tako/monitors/webhook-deliveries).
* `deliveries` records what happened on each channel. After 2 consecutive failed deliveries, Tako pauses the channel. See [Pause or resume a notification channel](/api-reference/notification-channels-update).
* A delivery's `state` is `channel_paused` when the channel was paused, so Tako didn't send a request. `failed` means the delivery ended without a `2xx`, including a delivery that expired before Tako sent it. Read `attempts` and `last_status_code` to tell them apart.
* `deliveries` covers the last 30 days. An older firing lists none.
* Tako removes firings older than the monitor type's `lookback_seconds`.


## OpenAPI

````yaml GET /v1/monitors/{id}/firings
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /v1/monitors/{id}/firings:
    parameters:
      - description: Resource id
        required: true
        schema:
          type: string
          format: uuid
        name: id
        in: path
    get:
      tags:
        - monitors
      summary: List a monitor's firings
      description: >-
        The occurrences this monitor has fired for, newest first. Tako removes
        firings older than the monitor type's lookback window. The deliveries
        list covers the last 30 days; an older firing lists none.


        **Experimental.** Request and payload shapes can change without a
        deprecation window. Monitors isn't recommended for production workflows.
      operationId: listMonitorFirings
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor.
          required: false
          schema:
            type: string
          name: cursor
          in: query
        - description: Max items to return (default 20, max 100).
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
          name: limit
          in: query
      responses:
        '200':
          description: The monitor's firings, newest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiringList'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
        - apiKey: []
components:
  schemas:
    FiringList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/FiringResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      required:
        - items
      title: FiringList
    BaseAPIError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
      type: object
      required:
        - error_message
        - error_type
      title: BaseAPIError
    FiringResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        monitor_id:
          type: string
          format: uuid
          title: Monitor Id
        fired_at:
          type: string
          format: date-time
          title: Fired At
        occurred_at:
          type: string
          format: date-time
          title: Occurred At
        trigger:
          $ref: '#/components/schemas/FiringTrigger'
        occurrence_key:
          type: string
          title: Occurrence Key
        payload:
          additionalProperties:
            $ref: '#/components/schemas/Scalar'
          type: object
          title: Payload
        deliveries:
          items:
            $ref: '#/components/schemas/DeliveryStatus'
          type: array
          title: Deliveries
        actions:
          items:
            $ref: '#/components/schemas/ActionRunStatus'
          type: array
          title: Actions
          description: >-
            One entry per action the monitor declared when it fired, in
            declaration order. deliveries lists only the firing's own event.
      type: object
      required:
        - id
        - monitor_id
        - fired_at
        - occurred_at
        - trigger
        - occurrence_key
        - payload
        - deliveries
        - actions
      title: FiringResponse
    APIErrorType:
      type: string
      enum:
        - BAD_REQUEST
        - AUTHENTICATION_ERROR
        - INTERNAL_SERVER_ERROR
        - RELEVANT_RESULTS_NOT_FOUND
        - RATE_LIMIT_EXCEEDED
        - PAYMENT_REQUIRED
        - REQUEST_TIMEOUT
        - FORBIDDEN
        - NOT_FOUND
        - SERVICE_UNAVAILABLE
        - SERVICE_OVERLOADED
        - UNSUPPORTED_CONTENT_FORMAT
        - PLACEHOLDER_CARD
        - VARIABLE_COST_NOT_REQUESTED
      title: APIErrorType
    FiringTrigger:
      type: string
      enum:
        - push
        - diff
      title: FiringTrigger
    Scalar:
      anyOf:
        - type: string
        - type: integer
        - type: number
        - type: boolean
        - type: 'null'
    DeliveryStatus:
      properties:
        channel_id:
          type: string
          format: uuid
          title: Channel Id
        state:
          $ref: '#/components/schemas/DeliveryState'
          description: >-
            How this delivery ended, or that it's still running. A paused
            channel reads channel_paused rather than failed, so you can tell a
            pause you caused from an endpoint that stopped accepting.
        attempts:
          type: integer
          title: Attempts
          description: >-
            How many delivery attempts Tako has started on the current run. Zero
            when it hasn't started one, which includes a delivery Tako re-drove
            for you.
        last_status_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Last Status Code
          description: >-
            The status code the most recent attempt received, which a re-drive
            keeps until the next attempt overwrites it. Null when no attempt got
            a response.
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
      type: object
      required:
        - channel_id
        - state
        - attempts
        - last_status_code
        - finished_at
      title: DeliveryStatus
    ActionRunStatus:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        position:
          type: integer
          title: Position
          description: >-
            The action's index in the monitor's actions list when the monitor
            fired.
        kind:
          type: string
          title: Kind
        state:
          $ref: '#/components/schemas/ActionRunState'
          description: >-
            How the run is going, or how it ended. pending and running are live.
            succeeded carries output. failed and skipped carry ended_reason and
            no output, and are delivered too.
        ended_reason:
          anyOf:
            - $ref: '#/components/schemas/ActionRunEndReason'
            - type: 'null'
          description: >-
            Why a run failed or was skipped. Null while the run is live and when
            it succeeded.
        output:
          anyOf:
            - $ref: '#/components/schemas/ActionOutput'
            - type: 'null'
          description: What the action produced. Null unless the run succeeded.
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
        deliveries:
          items:
            $ref: '#/components/schemas/DeliveryStatus'
          type: array
          title: Deliveries
          description: >-
            One entry per channel the run was delivered to, whatever its state.
            Empty when the action names no channels.
      type: object
      required:
        - id
        - position
        - kind
        - state
        - ended_reason
        - output
        - started_at
        - finished_at
        - deliveries
      title: ActionRunStatus
    DeliveryState:
      type: string
      enum:
        - pending
        - retrying
        - delivered
        - failed
        - channel_paused
      title: DeliveryState
      description: >-
        How a delivery to one channel is going, or how it ended. `pending` and
        `retrying` are live, and Tako is still working the retry ladder.
        `delivered` got a 2xx. `failed` means the delivery ended without a 2xx,
        which covers an endpoint that rejected every attempt and a row that
        expired before Tako posted at all; read `attempts` and
        `last_status_code` to tell those apart. `channel_paused` means the
        delivery ended without a 2xx because the channel is paused. Usually Tako
        stopped short of a request; when the pause landed while a request was
        out, `attempts` counts that request too. Resume the channel to receive
        later firings, and ask Tako to re-drive the firings the pause already
        stopped.
    ActionRunState:
      type: string
      enum:
        - pending
        - running
        - succeeded
        - failed
        - skipped
      title: ActionRunState
    ActionRunEndReason:
      type: string
      enum:
        - error
        - timeout
        - lease_expired
        - not_implemented
        - unknown_kind
        - unbindable
        - disabled
        - insufficient_balance
        - stale
      title: ActionRunEndReason
    ActionOutput:
      properties:
        text:
          type: string
          maxLength: 8000
          title: Text
          description: What the action produced, as text a person reads.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: >-
            A link to what the action produced, such as a card, a thread, or a
            report. Null when there's none.
        structured:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Structured
          description: >-
            The structured output the action filled, when it was asked for one.
            Null otherwise.
        structured_error:
          anyOf:
            - $ref: '#/components/schemas/AnswerStructuredOutputError'
            - type: 'null'
          description: >-
            Why `structured` is null when the action was asked for structured
            output and couldn't fill it. Null otherwise.
      type: object
      required:
        - text
      title: ActionOutput
    AnswerStructuredOutputError:
      properties:
        code:
          $ref: '#/components/schemas/AnswerStructuredOutputErrorCode'
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: AnswerStructuredOutputError
      description: Why structured_output is absent. The answer and the cards still return.
    AnswerStructuredOutputErrorCode:
      type: string
      enum:
        - arbiter_failed
        - validation_failed
        - internal_error
      title: AnswerStructuredOutputErrorCode
      description: |-
        Why Tako couldn't return structured output. Values are a public wire
        contract — never rename.
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.