# Keyword

Keyword.com is a digital marketing platform that provides search engine ranking tracking and SEO analytics

- **Category:** marketing
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 20
- **Triggers:** 0
- **Slug:** `KEYWORD`
- **Version:** 00000000_00

## Tools

### Add Keywords

**Slug:** `KEYWORD_ADD_KEYWORDS`

Tool to add keywords to a Keyword.com project for search ranking tracking. Use when you need to monitor how specific URLs rank for target keywords across different Google regions and devices.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | array | Yes | List of keyword objects to add. Each object contains keyword details like the phrase, URL, region, language, device type, and tags. You can add multiple keywords in a single request. |
| `project_name` | string | Yes | The name or identifier of the project/group to add keywords to. Must match an existing project in your Keyword.com account. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Archive Project

**Slug:** `KEYWORD_ARCHIVE_PROJECT`

Tool to archive a project in Keyword.com. Sets the project status to Archived. Use when you need to archive a project without permanently deleting it. The project will remain archived until restored or permanently deleted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_name` | string | Yes | The name of the project to archive. This is the project identifier used in the API path. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Project or Group

**Slug:** `KEYWORD_CREATE_PROJECT`

Tool to create a new project or group in Keyword.com account. Use when you need to create a new project for organizing keywords or create a group within an existing project. For groups, the category must follow the naming convention with [sub] delimiter (e.g., ProjectName[sub]GroupName).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | Yes | Project name or group name. For creating a project, use the project name (e.g., 'MyProject'). For creating a group within a project, use the format 'ProjectName[sub]GroupName' (e.g., 'MyProject[sub]MyGroup'). The [sub] delimiter is required for group creation. |
| `currency_code` | string | No | Optional 3-letter currency code for reporting (e.g., 'USD', 'GBP', 'EUR'). If not provided, the account's default currency will be used. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Keyword

**Slug:** `KEYWORD_DELETE_KEYWORD`

Tool to delete a single keyword from a project or group. Use when you need to permanently remove a keyword. Warning: This action cannot be undone and all historic ranking data will be lost.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `keyword_id` | string | Yes | The unique identifier of the keyword to delete. Warning: This action cannot be undone and all historic ranking data will be lost. |
| `project_name` | string | Yes | The name of the project or group containing the keyword (e.g., 'composio.dev') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Bulk delete keywords

**Slug:** `KEYWORD_DELETE_KEYWORDS_BULK`

Tool to bulk delete multiple keywords from a single project by providing keyword IDs. Use when you need to remove multiple keywords at once from a project.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | The unique identifier of the project from which keywords will be deleted. |
| `keyword_ids` | array | Yes | Array of keyword IDs to delete from the project. Each ID must belong to the specified project. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Project

**Slug:** `KEYWORD_DELETE_PROJECT`

Tool to delete a single project or group from Keyword.com. Use when you need to permanently remove a project. This action cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_name` | string | Yes | The name of the project or group to delete. This action cannot be undone and will permanently remove the project. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Current User

**Slug:** `KEYWORD_GET_CURRENT_USER`

Tool to retrieve the current authenticated user's account information. Returns user profile details including ID, name, email, onboarding status, and optionally subscription information.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `include_subscriptions` | boolean | No | Include subscription details in response |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Keyword

**Slug:** `KEYWORD_GET_KEYWORD`

Tool to retrieve all keyword settings and ranking metrics for a single keyword. Use when you need to get detailed information about a keyword's performance and configuration. Can optionally retrieve data for a specific date.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `date` | string | No | Optional date to retrieve keyword data for a specific date. Format: YYYY-MM-DD. |
| `keyword_id` | string | Yes | The unique identifier of the keyword to retrieve. |
| `project_name` | string | Yes | The project name (domain) that the keyword belongs to. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Project Details

**Slug:** `KEYWORD_GET_PROJECT`

Tool to retrieve a single project's summary from Keyword.com. Returns groups, tags, keyword counts, and the PROJECT AUTH KEY required for detailed data collection. Use when you need project details or the auth key for further API operations.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_name` | string | Yes | The project name or domain to retrieve (e.g., 'composio.dev') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Project Metrics

**Slug:** `KEYWORD_GET_PROJECT_METRICS`

Retrieve keyword movement metrics for a project, group, or tag. Returns ranking changes (daily, weekly, or monthly) including number of keywords that improved, declined, or remained unchanged, along with detailed movement data for individual keywords.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `timeframe` | string ("daily" | "weekly" | "monthly") | Yes | Timeframe for metrics calculation. Determines the period for ranking changes. |
| `project_name` | string | Yes | The name of the project, group, or tag to retrieve metrics for (e.g., 'composio.dev') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Keyword Ranking History

**Slug:** `KEYWORD_GET_RANKING_HISTORY`

Tool to retrieve Google ranking history for specified keywords for up to 180 days. Use when you need to analyze historical ranking trends or track keyword performance over time. Returns daily ranking positions grouped by keyword ID and domain.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `kwid` | array | Yes | Array of keyword IDs to retrieve ranking history for. Each ID should be a valid keyword ID from your Keyword.com account. |
| `limit` | integer | No | Number of days of ranking history to retrieve. Maximum value is 180 days. If not specified, returns the default number of days. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Share of Voice History

**Slug:** `KEYWORD_GET_SOV_HISTORY`

Retrieve Share of Voice data over time for a specific project. Use when you need historical SOV metrics. Supports ranges of 7, 30, 90, 180, and 365 days with varying data point intervals.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | The unique identifier of the project for which to retrieve Share of Voice data |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Top Pages

**Slug:** `KEYWORD_GET_TOP_PAGES`

Tool to retrieve Top Pages data for a project showing ranking URLs with keyword counts, average rank, search volume, and cost per click metrics. Use when you need to analyze which pages are ranking for the most keywords in a project.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_name` | string | Yes | The name or identifier of the project/group to retrieve top pages for. This is typically the domain name (e.g., 'composio.dev'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Active Projects

**Slug:** `KEYWORD_LIST_ACTIVE_PROJECTS`

Tool to retrieve all active projects with their groups, tags, and keyword counts. Returns PROJECT AUTH KEY for each project which is required to collect detailed project and keyword data.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Alerts

**Slug:** `KEYWORD_LIST_ALERTS`

Tool to retrieve all alerts for the Keyword.com account with pagination and sorting options. Use when you need to fetch alerts, check alert status, or monitor notifications. Supports filtering by view type and retrieving only recent alerts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `last` | boolean | No | When true, retrieves only the most recent alerts. Useful for getting latest notifications without pagination. |
| `page` | integer | No | Page number for pagination (starts at 1). Use with per_page to navigate through alerts. |
| `per_page` | integer | No | Number of results per page (e.g., 100). Controls how many alerts are returned in a single request. |
| `view_type` | string | No | Filter alerts by view type (e.g., 'All alerts'). Narrows results to specific alert categories or statuses. |
| `sort_field` | string | No | Field to sort results by (e.g., 'created_at', 'updated_at'). Determines the ordering of alerts in the response. |
| `sort_direction` | string ("asc" | "desc") | No | Sort direction for results. Use 'asc' for ascending order (oldest first) or 'desc' for descending order (newest first). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Keywords

**Slug:** `KEYWORD_LIST_KEYWORDS`

Tool to retrieve all keywords and their ranking data in a project or group. Use when you need to get keyword rankings, search volumes, and position changes. Supports pagination with per_page (max 250) and page parameters, and can filter by specific date.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `date` | string | No | Optional date to retrieve keyword data for a specific date. Format: YYYY-MM-DD. |
| `page` | integer | No | Page number for pagination. Starts at 1. |
| `per_page` | integer | No | Number of keywords to return per page. Maximum 250. |
| `project_name` | string | Yes | The project name (domain) to retrieve keywords from. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Project Regions

**Slug:** `KEYWORD_LIST_PROJECT_REGIONS`

Tool to list all Google regions being tracked in a Keyword.com project. Returns each region with the count of keywords being monitored in that region. Use when you need to see which geographic regions are configured for keyword tracking in a specific project.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_name` | string | Yes | The name or identifier of the project (group) to retrieve regions for. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Refresh Keywords

**Slug:** `KEYWORD_REFRESH_KEYWORDS`

Tool to trigger an on-demand update for all keywords in one or more projects or groups. Use when you need to refresh keyword rankings data immediately instead of waiting for the scheduled update. Returns the number of refreshes remaining for the day.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_ids` | array | Yes | List of project IDs that need to be refreshed. You must provide at least one project ID. |
| `include_sub_groups` | boolean | No | Set to true to refresh all keywords in the project and its sub-groups. If false, only refreshes keywords in the specified projects. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Restore Archived Project

**Slug:** `KEYWORD_RESTORE_PROJECT`

Tool to restore an archived project or group. Use when you need to unarchive a project and resume keyword tracking. Once restored, keywords will automatically update during the next scheduled cycle.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_name` | string | Yes | The name of the project or group to restore from archive. Once restored, keywords will automatically update during the next scheduled cycle. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Keywords

**Slug:** `KEYWORD_UPDATE_KEYWORDS`

Tool to update keyword settings in a project. Updates tracking parameters such as device type, tracked URL, Google region, language, and URL tracking method for multiple keywords at once. Use when you need to modify keyword tracking configuration.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | Yes | JSON:API formatted data containing keyword update information. |
| `project_id` | string | Yes | The unique identifier of the project containing the keywords to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |