---
title: "Change flow status"
method: PUT
path: "/v2/flows/{id}/status"
tags: ["Flows Api Service"]
---

# Change flow status

`PUT /v2/flows/{id}/status`

## Request

- Base URL: `https://app.metricool.com/api`
- URL: `https://app.metricool.com/api/v2/flows/{id}/status`
- Auth: none declared

Activating a flow requires its template to be available for the brand and the caller; deactivating one never does, so a running flow can always be switched off from its brand.

## Path parameters

- `id` integer, required

## Request body

- ChangeFlowStatusRequest: Request body for changing a flow's status
  - `status` string, required: New flow status

## Response `200`

Flow status changed successfully

- JsonOkResponseFlowResponseDto
  - `metadata` object
  - `page` JsonPaging
    - `next` string
  - `data` FlowResponseDto: Detailed representation of a flow including configuration and creator information
    - `id` integer, required: Flow identifier
    - `name` string, required: Flow name
    - `flowType` string, required: Type of flow
    - `socialNetwork` string, required: Social network associated with the flow
    - `status` string, required: Current flow status
    - `triggerConfig` object, required: Trigger configuration map defining when the flow is activated
    - `actionsConfig` object, required: Actions configuration map defining what the flow does when triggered
    - `creatorUserId` integer: Creator user identifier
    - `creatorAgencyId` integer: Creator agency identifier
    - `creatorAgencyUserId` integer: Creator agency user identifier
    - `createdAt` DateTimeInfo, required
      - `dateTime` string, required: Local Date-time represented with a certain timezone
      - `timezone` string: Timezone applied to the datetime
    - `lastExecutionAt` DateTimeInfo, required
      - `dateTime` string, required: Local Date-time represented with a certain timezone
      - `timezone` string: Timezone applied to the datetime
    - `updatedAt` DateTimeInfo, required
      - `dateTime` string, required: Local Date-time represented with a certain timezone
      - `timezone` string: Timezone applied to the datetime
    - `profileConnected` boolean, required: Whether the social network profile is currently connected

## Other responses

- `400`: A configuration the backend rejects comes back with title `DomainValidationException` and a `detail` object keyed by code (the codes below); each value is the message, naming the action position (`order`) when it applies. When the same code is raised more than once, its messages are merged into one value separated by spaces: ```json {"status":"BAD_REQUEST","code":"400","title":"DomainValidationException", "detail":{"MISSING_FIRST_DM":"A DM action at position 1 is required to activate the flow"}} ``` Validation runs in phases and stops at the first phase that fails, so fixing one batch of codes may reveal the next. Changing to `ACTIVE` re-validates the stored configuration: structure, then activation rules. The save rules are not re-run here. | Code | Flow types | Meaning and fix | |---|---|---| | `INVALID_TRIGGER_STRUCTURE` | All | `triggerConfig` does not match the flow type's schema (a field of the wrong type or, for most flow types, an unknown field). Send the fields documented for the flow type. | | `INVALID_ACTIONS_STRUCTURE` | All | `actionsConfig` does not match the schema, or `actions` contains a `null` element. | | `TOO_MANY_ACTIONS` | All | More actions than the flow type allows: 3 for `COMMENT_WITH_KEYWORD`, 2 for `X_REPOST_UNPOST`, 1 for the rest. | | `ACTIONS_NOT_ORDERED` | All | `order` values must be unique and strictly ascending in the `actions` array. | | `UNRECOGNIZED_ACTION_CONFIG` | All | An action's `order` does not exist for the flow type, or its `config` does not fit the action expected at that position. `COMMENT_WITH_KEYWORD`: 0 reply, 1 first DM, 2 second DM with button. `X_REPOST_UNPOST`: 0 repost, 1 unpost. Other types: 0. | | `MISSING_POST_SCOPE` | `COMMENT_WITH_KEYWORD`, `STORY_WITH_KEYWORD`, `TK_COMMENT_WITH_KEYWORD`, `TK_HIDE_WITH_KEYWORD`, `X_REPOST_UNPOST`, `X_COMMENT_TO_DM` | `triggerConfig.postScope` is required to activate. | | `UNSUPPORTED_POST_SCOPE` | `X_REPOST_UNPOST` | `PUBLISHED_POSTS` is not supported yet; use another scope. | | `MISSING_POST_IDS` | `X_REPOST_UNPOST` | Every scope except `ALL_POSTS` needs at least one id in `triggerConfig.postIds`. | | `MISSING_FIRST_DM` | `COMMENT_WITH_KEYWORD` | The DM action at `order` 1 is required to activate. | | `MISSING_DM_TEXT` | `COMMENT_WITH_KEYWORD`, `DM_KEYWORD_TO_DM`, `STORY_WITH_KEYWORD`, `X_DM_KEYWORD_TO_DM`, `X_COMMENT_TO_DM` | The DM (`order` 1 in `COMMENT_WITH_KEYWORD`, 0 in the rest) has no `message`, or, except in `COMMENT_WITH_KEYWORD`, is missing. In `COMMENT_WITH_KEYWORD` a missing first DM returns `MISSING_FIRST_DM` instead. | | `URL_NOT_ALLOWED_IN_FIRST_DM` | `COMMENT_WITH_KEYWORD` | The first DM's `message` cannot contain URLs; put the link in the second DM's button. | | `INCOMPLETE_BUTTON` | `COMMENT_WITH_KEYWORD` (`order` 2), `DM_KEYWORD_TO_DM`, `STORY_WITH_KEYWORD` | `buttonText` and `link` must be sent together, or neither. | | `INVALID_BUTTON_LINK` | `COMMENT_WITH_KEYWORD` (`order` 2), `DM_KEYWORD_TO_DM`, `STORY_WITH_KEYWORD` | The button `link` is not an absolute `http`/`https` URL. | | `TEXT_TOO_LONG` | `COMMENT_WITH_KEYWORD` (`order` 2), `DM_KEYWORD_TO_DM`, `STORY_WITH_KEYWORD`, `X_DM_KEYWORD_TO_DM` | On activation: `buttonText` over 200 or button `link` over 2000 characters; in `X_DM_KEYWORD_TO_DM`, `link` over 2000 characters. | | `INVALID_LINK` | `X_DM_KEYWORD_TO_DM` | On activation: `link` is not an absolute `http`/`https` URL. | | `BUTTON_REQUIRES_MESSAGE` | `COMMENT_WITH_KEYWORD` | The second DM (`order` 2) has a valid button but no `message`. Add the message or remove `buttonText` and `link`. | | `MISSING_REPLY` | `TK_COMMENT_WITH_KEYWORD` | The reply action at `order` 0 needs at least one non-blank comment in `postComments`. | | `MISSING_HIDE_ACTION` | `TK_HIDE_WITH_KEYWORD` | The hide action at `order` 0 is required to activate. | | `MISSING_REPOST_ACTION` | `X_REPOST_UNPOST` | The repost action at `order` 0 is required (the unpost is optional). | | `MISSING_ACTION_DELAY` | `X_REPOST_UNPOST` | The repost and unpost actions must include `delaySeconds`. | | `UNPOST_DELAY_NOT_POSITIVE` | `X_REPOST_UNPOST` | The unpost `delaySeconds` must be above 0: it is counted from the repost. | Also 400 when `status` is missing or is not `DRAFT`, `ACTIVE` or `INACTIVE` (title `ValidationError`, `detail` keyed by field name: `{"status":"..."}`), and when the social profile is not connected (title `FlowProfileDisconnectedException`).
- `401`: User not authenticated
- `403`: Insufficient permissions, subscription plan does not support Flows, or the template is not available when activating
- `404`: Flow not found

---

[API](https://skmtc.dev/metricool/apis/metricool-api.md) · [All operations](https://skmtc.dev/metricool/apis/metricool-api/llms.txt) · [OpenAPI document](https://skmtc.dev/metricool/apis/metricool-api/revisions/aea9d9a8415a?raw)