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

# Quickstart

> Get started with the Vantage API.

<Info>
  This quickstart guide will walk you through building a complete cost management workflow using the Vantage API. You'll learn to create folders, generate Cost Reports, and analyze spending data programmatically.
</Info>

## Prerequisites

* A [Vantage account](https://console.vantage.sh/) with at least one provider integration
* A Vantage [API access token](/api/authentication) with Read and Write scopes enabled

<Card title="Base URL" icon="code">
  All Vantage API `v2` requests use the following base URL:

  ```bash theme={null}
  https://api.vantage.sh/v2
  ```
</Card>

In this quickstart, we'll cover the following steps:

<Steps>
  <Step title="Discover Workspaces">
    First, we'll retrieve all workspaces your API token has access to.
  </Step>

  <Step title="Create Organization">
    Set up a folder structure to organize your Cost Reports.
  </Step>

  <Step title="Generate Cost Report">
    Create a VQL-powered Cost Report with specific filters.
  </Step>

  <Step title="Analyze Data">
    Retrieve and analyze cost and usage data from your report.
  </Step>
</Steps>

<Info>
  This quickstart focuses on API-native resource creation and data retrieval. If you need a point-in-time CSV (including a CSV export in the FOCUS schema) or PDF that mirrors a Cost Report in the UI, use the [Cost Report export flow](/cost_reports#export-cost-reports) instead.
</Info>

## Step 1: Discover Your Workspaces

<Tabs>
  <Tab title="Request">
    <Card title="GET /workspaces" icon="database">
      Retrieve all workspaces your API token has access to. This endpoint returns workspace tokens and metadata that you'll use in subsequent API calls.
    </Card>

    ```bash theme={null}
    curl --request GET \
         --url https://api.vantage.sh/v2/workspaces \
         --header 'accept: application/json' \
         --header 'authorization: Bearer ACCESS_TOKEN'
    ```
  </Tab>

  <Tab title="Response">
    <Card title="Success Response" icon="check">
      The response includes pagination links and an array of workspace objects with tokens, names, and configuration details.
    </Card>

    ```json theme={null}
    {
      "links": {
        "self": "https://api.vantage.sh/v2/workspaces",
        "first": "https://api.vantage.sh/v2/workspaces?page=1",
        "next": null,
        "last": "https://api.vantage.sh/v2/workspaces?page=1",
        "prev": null
      },
      "workspaces": [
        {
          "token": "wrkspc_123445abcde",
          "name": "Management",
          "created_at": "2023-10-01T01:00:56Z",
          "enable_currency_conversion": false,
          "currency": "USD",
          "exchange_rate_date": "daily_rate"
        },
        {
          "token": "wrkspc_5678fghijk",
          "name": "Marketing",
          "created_at": "2023-10-01T01:00:56Z",
          "enable_currency_conversion": false,
          "currency": "USD",
          "exchange_rate_date": "daily_rate"
        }
      ]
    }
    ```

    <Note>
      Save the workspace tokens from this response. You'll need them for creating folders and Cost Reports in the next steps.
    </Note>

    <Info>
      If your account uses multiple workspaces or team-scoped service tokens, choose a workspace that your token can access and use that `workspace_token` consistently in your create requests.
    </Info>
  </Tab>
</Tabs>

## Step 2: Create an Organized Folder Structure

<Tabs>
  <Tab title="Request">
    <Card title="POST /folders" icon="database">
      Create a folder to organize your Cost Reports. This helps maintain a clean structure for your cost management workflows.
    </Card>

    ```bash theme={null}
    curl --request POST \
         --url https://api.vantage.sh/v2/folders \
         --header 'accept: application/json' \
         --header 'authorization: Bearer ACCESS_TOKEN' \
         --header 'content-type: application/json' \
         --data '{
      "title": "Team Reports",
      "workspace_token": "wrkspc_123445abcde"
    }'
    ```

    <Info>
      Use the workspace token from Step 1. You can also specify a `parent_folder_token` to create nested folder structures.
    </Info>
  </Tab>

  <Tab title="Response">
    <Card title="Success Response" icon="check">
      The response includes the new folder's token, which you'll use when creating Cost Reports.
    </Card>

    ```json theme={null}
    {
      "token": "fldr_123456abcde123",
      "title": "Team Reports",
      "parent_folder_token": null,
      "saved_filter_tokens": [],
      "created_at": "2023-10-09T13:24:33Z",
      "updated_at": "2023-10-09T13:24:33Z",
      "workspace_token": "wrkspc_123445abcde"
    }
    ```

    <Note>
      Save the folder token (`fldr_123456abcde123`). You'll need it in the next step to create your Cost Report.
    </Note>
  </Tab>
</Tabs>

## Step 3: Create an Intelligent Cost Report

<Card title="VQL" icon="bolt">
  This step demonstrates the power of **Vantage Query Language (VQL)**, a flexible query system that lets you filter costs by provider, tags, services, and more. Learn more about [VQL syntax](/vql).
</Card>

<Tabs>
  <Tab title="Request">
    <Card title="POST /cost_reports" icon="database">
      Create a VQL-powered Cost Report that automatically filters AWS production costs.
    </Card>

    ```bash theme={null}
    curl --request POST \
         --url https://api.vantage.sh/v2/cost_reports \
         --header 'accept: application/json' \
         --header 'authorization: Bearer <ACCESS_TOKEN>' \
         --header 'content-type: application/json' \
         --data '{
      "settings": {
        "include_credits": false,
        "include_refunds": false,
        "include_discounts": true,
        "include_tax": true,
        "amortize": true,
        "unallocated": false,
        "aggregate_by": "cost",
        "show_previous_period": true
      },
      "chart_type": "line",
      "date_bin": "cumulative",
      "title": "AWS Production Costs",
      "folder_token": "fldr_123456abcde123",
      "filter": "costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'"
    }'
    ```

    <AccordionGroup>
      <Accordion title="VQL Filter Breakdown" icon="code">
        The VQL filter `costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'` does the following:

        * **`costs.provider = 'aws'`** - Only includes AWS costs
        * **`tags.name = 'environment'`** - Filters for resources with an `environment` tag
        * **`tags.value = 'production'`** - Only includes resources tagged as `production`

        This creates a focused report showing only your production AWS spending.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Response">
    <Card title="Success Response" icon="check">
      The response includes the Cost Report token and all configuration details. This token is needed for retrieving cost data in the next step.
    </Card>

    ```json theme={null}
    {
      "token": "rprt_1234a5678b1ab234",
      "title": "AWS Production Costs",
      "folder_token": "fldr_123456abcde123",
      "saved_filter_tokens": [],
      "filter": "costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'",
      "groupings": "provider,service",
      "settings": {
        "include_credits": false,
        "include_refunds": false,
        "include_discounts": true,
        "include_tax": true,
        "amortize": true,
        "unallocated": false,
        "aggregate_by": "cost"
      },
      "created_at": "2023-10-09T15:51:48Z",
      "workspace_token": "wrkspc_123445abcde",
      "previous_period_start_date": null,
      "previous_period_end_date": null,
      "start_date": "2024-07-01",
      "end_date": "2024-07-31",
      "date_interval": "this_month",
      "chart_type": "bar",
      "date_bin": "day"
    }
    ```

    <Info>
      Save the report token (`rprt_1234a5678b1ab234`) - you'll use it to retrieve cost data in the next step.
    </Info>
  </Tab>
</Tabs>

## Step 4: Analyze Your Cost Data

<Tabs>
  <Tab title="Request">
    <Card title="GET /costs" icon="database">
      Retrieve detailed cost data from your report with flexible filtering and grouping options. This demonstrates how to extract actionable insights from your cost data.
    </Card>

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc' \
         --header 'accept: application/json' \
         --header 'authorization: Bearer <ACCESS_TOKEN>'
    ```

    <AccordionGroup>
      <Accordion title="Query Parameters Explained" icon="code">
        * **`cost_report_token`** - Uses the report token from Step 3
        * **`start_date` & `end_date`** - ISO 8601 date range for filtering
        * **`groupings=service`** - Groups costs by AWS service (EC2, RDS, etc.)
        * **`order=desc`** - Sorts by date in descending order (newest first)
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Response">
    <Card title="Cost Data Response" icon="check">
      The response includes pagination links, total cost summary, and detailed cost breakdowns by service.
    </Card>

    ```json theme={null}
    {
      "links": {
        "self": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc",
        "first": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1",
        "next": null,
        "last": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1",
        "prev": null
      },
      "total_cost": {
        "amount": "1000.11",
        "currency": "USD"
      },
      "costs": [
        {
          "accrued_at": "2023-12-31",
          "amount": "300.05",
          "currency": "USD",
          "provider": "aws",
          "account_id": "123456789012",
          "service": "AmazonRDS"
        },
        {
          "accrued_at": "2023-12-28",
          "amount": "500.03",
          "currency": "USD",
          "provider": "aws",
          "account_id": "123456789012",
          "service": "AmazonVPC"
        },
        {
          "accrued_at": "2023-12-24",
          "amount": "200.03",
          "currency": "USD",
          "provider": "aws",
          "account_id": "123456789012",
          "service": "AmazonECS"
        }
      ]
    }
    ```

    <Info>
      This data structure is perfect for building cost dashboards, automated alerts, and financial reporting tools.
    </Info>
  </Tab>
</Tabs>

## Bonus: Retrieve Usage Analytics

<Card title="Usage Data Insights" icon="bolt">
  Beyond cost data, the Vantage API provides detailed usage analytics. This is perfect for understanding resource utilization patterns and optimizing your infrastructure.
</Card>

<Tabs>
  <Tab title="Request">
    <Card title="GET /costs with Usage Data" icon="database">
      Retrieve both cost and usage data by setting `aggregate_by=usage`. This provides comprehensive resource utilization insights.
    </Card>

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&order=desc&settings%5Binclude_credits%5D=false&settings%5Binclude_refunds%5D=false&settings%5Binclude_discounts%5D=true&settings%5Binclude_tax%5D=true&settings%5Bamortize%5D=true&settings%5Bunallocated%5D=false&settings%5Baggregate_by%5D=usage' \
         --header 'accept: application/json' \
         --header 'authorization: Bearer TOKEN'
    ```

    <Info>
      The key parameter here is `settings[aggregate_by]=usage` which switches from cost aggregation to usage aggregation.
    </Info>
  </Tab>

  <Tab title="Response">
    <Card title="Usage Analytics Response" icon="check">
      The response includes both cost and usage data, providing comprehensive insights into your resource utilization patterns.
    </Card>

    ```json theme={null}
    {
      "links": {
        "self": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc",
        "first": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1",
        "next": null,
        "last": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1",
        "prev": null
      },
      "total_cost": {
        "amount": "75455.01",
        "currency": "USD"
      },
      "total_usage": [
        {
          "amount": "0.0",
          "unit": ""
        },
        {
          "amount": "147793.33",
          "unit": "Hrs"
        },
        {
          "amount": "8929.98",
          "unit": "Hours"
        }
      ],
      "costs": [ 
        {
          "accrued_at": "2025-01-06",
          "amount": "885.4577627912",
          "currency": "USD",
          "usage": {
            "amount": "910.969248694",
            "unit": "Hrs"
          },
          "provider": "aws",
          "account_id": "123456789012",
          "service": "AmazonEC2"
        },
        {
          "accrued_at": "2025-01-06",
          "amount": "19.4873999955",
          "currency": "USD",
          "usage": {
            "amount": "142.9999999995",
            "unit": "Hrs"
          },
          "provider": "aws",
          "account_id": "123456789012",
          "service": "AmazonEC2"
        }
      ]
    }
    ```

    <Info>
      This usage data is perfect for building resource optimization tools and capacity planning dashboards.
    </Info>
  </Tab>
</Tabs>

<Card title="What You've Accomplished" icon="check">
  You've successfully built a complete cost management workflow using the Vantage API:

  * Discovered workspaces and retrieved access tokens
  * Created organized folders for Cost Report management
  * Generated intelligent Cost Reports using VQL filtering
  * Analyzed cost data with flexible grouping and filtering
  * Retrieved usage analytics for resource optimization
</Card>