プロセスタイム取得API

概要

このAPIは、指定したIssueをルートとした階層構造と、各Issueのプロセスタイム統計情報を取得します。

企画・要件定義・設計・実装・テスト・リリースの各6フェーズの作業時間（時間単位）、割合、および各フェーズ間の待機時間を提供します。

エンドポイント

GET /api/external/v1/issues/process_time/tree

リクエストパラメータ

クエリパラメータ

パラメータ名型必須説明デフォルト
urlString○IssueのURL（例: https://example.atlassian.net/browse/EPIC-123）–
max_depthInteger–ルートからの最大階層深度（0〜2）1
pageInteger–ページ番号1
per_pageInteger–1ページあたりの件数（最大: 30）10

max_depthの動作

max_depth値取得範囲例
0ルートIssueのみEpicのみ
1（デフォルト）ルート + 直下の子Epic + Story
2（最大）ルート + 子 + 孫Epic + Story + Task
  • 2を超える値を指定した場合、2に制限される
  • 負の値を指定した場合、デフォルト1が適用される
  • 省略した場合、デフォルト1が適用される

リクエストヘッダー

ヘッダー名値必須説明
AuthorizationBearer {access_token}○APIキー（スコープ：stats:read)
X-Organization-Name{org_name}○組織名（ログイン時に使用する組織ID）

リクエストサンプル

基本的なツリー取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

max_depth指定で取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ページネーション指定

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2&page=1&per_page=20>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

バリデーション

このAPIでは、以下のバリデーションが行われます:

  1. url
    • 必須パラメータ（未指定の場合は400エラー）
    • 存在するIssueのURLである必要がある（存在しない場合は404エラー）
  2. max_depth
    • オプションパラメータ（デフォルト: 1）
    • 0〜2の範囲で指定（2を超える値は2に制限、負の値はデフォルト1）
  3. ページネーションパラメータ
    • pageは1以上の整数（0以下の場合は1として扱われる）
    • per_pageは1以上30以下の整数（0以下の場合は10、30を超える場合は30として扱われる）
  4. 認証
    • 有効なアクセストークン（スコープstats:read）が必要
    • X-Organization-Nameヘッダーが必要
    • トークンは指定された組織へのアクセス権限を持っている必要がある

レスポンス

成功時 (200 OK)

ツリーデータが存在する場合

{
  "root": "<https://example.atlassian.net/browse/EPIC-123>",
  "issues": [
    {
      "url": "<https://example.atlassian.net/browse/EPIC-123>",
      "name": "バックエンド改善プロジェクト",
      "parent": null,
      "depth": 0,
      "stats": {
        "planning": {
          "hours": 120.0,
          "rate": 12.5
        },
        "requirements": {
          "hours": 192.0,
          "rate": 20.0,
          "wait_before": {
            "hours": 24.0,
            "rate": 2.5
          }
        },
        "design": {
          "hours": 72.0,
          "rate": 7.5,
          "wait_before": {
            "hours": 48.0,
            "rate": 5.0
          }
        },
        "coding": {
          "hours": 240.0,
          "rate": 25.0,
          "wait_before": {
            "hours": 72.0,
            "rate": 7.5
          }
        },
        "testing": {
          "hours": 96.0,
          "rate": 10.0,
          "wait_before": {
            "hours": 36.0,
            "rate": 3.75
          }
        },
        "release": {
          "hours": 48.0,
          "rate": 5.0,
          "wait_before": {
            "hours": 12.0,
            "rate": 1.25
          }
        }
      }
    },
    {
      "url": "<https://example.atlassian.net/browse/STORY-1>",
      "name": "API設計",
      "parent": "<https://example.atlassian.net/browse/EPIC-123>",
      "depth": 1,
      "stats": {
        "planning": {
          "hours": 0.0,
          "rate": 0.0
        },
        "requirements": {
          "hours": null,
          "rate": null,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "design": {
          "hours": null,
          "rate": null,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "coding": {
          "hours": 480.0,
          "rate": 85.1,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "testing": {
          "hours": 84.0,
          "rate": 14.9,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "release": {
          "hours": null,
          "rate": null,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        }
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 1,
    "total_count": 2
  }
}

プロセスタイム統計がないIssueの場合

{
  "root": "<https://example.atlassian.net/browse/TASK-456>",
  "issues": [
    {
      "url": "<https://example.atlassian.net/browse/TASK-456>",
      "name": "タスク名",
      "parent": null,
      "depth": 0,
      "stats": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 1,
    "total_count": 1
  }
}

レスポンスフィールド

フィールド型説明
rootStringルートIssueのURL
issuesArrayIssue情報の配列
urlStringIssueのURL
nameStringIssueのタイトル
parentString/null親IssueのURL（ルートの場合はnull）
depthIntegerルートからの相対的な深さ（0がルート）
statsObject/nullプロセスタイム統計（統計がない場合はnull）
planningObject企画フェーズ
hoursFloat/null作業時間（時間単位）
rateFloat/null全体に対する割合（%）
requirementsObject要件定義フェーズ
hoursFloat/null作業時間（時間単位）
rateFloat/null全体に対する割合（%）
wait_beforeObject前フェーズからの待機時間
designObject設計フェーズ（requirementsと同構造）
codingObject実装フェーズ（requirementsと同構造）
testingObjectテストフェーズ（requirementsと同構造）
releaseObjectリリースフェーズ（requirementsと同構造）
paginationObjectページネーション情報
current_pageInteger現在のページ番号
per_pageInteger1ページあたりの件数
total_pagesInteger総ページ数
total_countInteger総件数

エラー時

ステータスコードエラー内容説明
400Bad Requesturlパラメータが未指定
401Unauthorized認証エラー
• トークンが無効
• 組織名が無効
404Not FoundIssueが見つからない

エラーレスポンス例

{
  "error": {
    "type": "bad_request",
    "message": "url parameter is required"
  }
}
{
  "error": {
    "type": "unauthorized",
    "message": "Unauthorized"
  }
}
{
  "error": {
    "type": "not_found",
    "message": "Not Found"
  }
}

使用例

エピックのツリーを取得（デフォルト）

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

エピックのツリーを孫まで取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ルートIssueのみ取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=0>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ページネーション指定で取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2&page=2&per_page=5>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ストーリーをルートとして取得

エピック以外のIssueもルートとして指定できます。その場合、指定したIssueがdepth=0となり、直下の子Issueがdepth=1で表示されます。

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FSTORY-1&max_depth=1>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

概要

このAPIは、指定したIssueをルートとした階層構造と、各Issueのプロセスタイム統計情報を取得します。

企画・要件定義・設計・実装・テスト・リリースの各6フェーズの作業時間（時間単位）、割合、および各フェーズ間の待機時間を提供します。

エンドポイント

GET /api/external/v1/issues/process_time/tree

リクエストパラメータ

クエリパラメータ

パラメータ名型必須説明デフォルト
urlString○IssueのURL（例: https://example.atlassian.net/browse/EPIC-123）–
max_depthInteger–ルートからの最大階層深度（0〜2）1
pageInteger–ページ番号1
per_pageInteger–1ページあたりの件数（最大: 30）10

max_depthの動作

max_depth値取得範囲例
0ルートIssueのみEpicのみ
1（デフォルト）ルート + 直下の子Epic + Story
2（最大）ルート + 子 + 孫Epic + Story + Task
  • 2を超える値を指定した場合、2に制限される
  • 負の値を指定した場合、デフォルト1が適用される
  • 省略した場合、デフォルト1が適用される

リクエストヘッダー

ヘッダー名値必須説明
AuthorizationBearer {access_token}○APIキー（スコープ：stats:read)
X-Organization-Name{org_name}○組織名（ログイン時に使用する組織ID）

リクエストサンプル

基本的なツリー取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

max_depth指定で取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ページネーション指定

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2&page=1&per_page=20>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

バリデーション

このAPIでは、以下のバリデーションが行われます:

  1. url
    • 必須パラメータ（未指定の場合は400エラー）
    • 存在するIssueのURLである必要がある（存在しない場合は404エラー）
  2. max_depth
    • オプションパラメータ（デフォルト: 1）
    • 0〜2の範囲で指定（2を超える値は2に制限、負の値はデフォルト1）
  3. ページネーションパラメータ
    • pageは1以上の整数（0以下の場合は1として扱われる）
    • per_pageは1以上30以下の整数（0以下の場合は10、30を超える場合は30として扱われる）
  4. 認証
    • 有効なアクセストークン（スコープstats:read）が必要
    • X-Organization-Nameヘッダーが必要
    • トークンは指定された組織へのアクセス権限を持っている必要がある

レスポンス

成功時 (200 OK)

ツリーデータが存在する場合

{
  "root": "<https://example.atlassian.net/browse/EPIC-123>",
  "issues": [
    {
      "url": "<https://example.atlassian.net/browse/EPIC-123>",
      "name": "バックエンド改善プロジェクト",
      "parent": null,
      "depth": 0,
      "stats": {
        "planning": {
          "hours": 120.0,
          "rate": 12.5
        },
        "requirements": {
          "hours": 192.0,
          "rate": 20.0,
          "wait_before": {
            "hours": 24.0,
            "rate": 2.5
          }
        },
        "design": {
          "hours": 72.0,
          "rate": 7.5,
          "wait_before": {
            "hours": 48.0,
            "rate": 5.0
          }
        },
        "coding": {
          "hours": 240.0,
          "rate": 25.0,
          "wait_before": {
            "hours": 72.0,
            "rate": 7.5
          }
        },
        "testing": {
          "hours": 96.0,
          "rate": 10.0,
          "wait_before": {
            "hours": 36.0,
            "rate": 3.75
          }
        },
        "release": {
          "hours": 48.0,
          "rate": 5.0,
          "wait_before": {
            "hours": 12.0,
            "rate": 1.25
          }
        }
      }
    },
    {
      "url": "<https://example.atlassian.net/browse/STORY-1>",
      "name": "API設計",
      "parent": "<https://example.atlassian.net/browse/EPIC-123>",
      "depth": 1,
      "stats": {
        "planning": {
          "hours": 0.0,
          "rate": 0.0
        },
        "requirements": {
          "hours": null,
          "rate": null,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "design": {
          "hours": null,
          "rate": null,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "coding": {
          "hours": 480.0,
          "rate": 85.1,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "testing": {
          "hours": 84.0,
          "rate": 14.9,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        },
        "release": {
          "hours": null,
          "rate": null,
          "wait_before": {
            "hours": null,
            "rate": null
          }
        }
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 1,
    "total_count": 2
  }
}

プロセスタイム統計がないIssueの場合

{
  "root": "<https://example.atlassian.net/browse/TASK-456>",
  "issues": [
    {
      "url": "<https://example.atlassian.net/browse/TASK-456>",
      "name": "タスク名",
      "parent": null,
      "depth": 0,
      "stats": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 1,
    "total_count": 1
  }
}

レスポンスフィールド

フィールド型説明
rootStringルートIssueのURL
issuesArrayIssue情報の配列
urlStringIssueのURL
nameStringIssueのタイトル
parentString/null親IssueのURL（ルートの場合はnull）
depthIntegerルートからの相対的な深さ（0がルート）
statsObject/nullプロセスタイム統計（統計がない場合はnull）
planningObject企画フェーズ
hoursFloat/null作業時間（時間単位）
rateFloat/null全体に対する割合（%）
requirementsObject要件定義フェーズ
hoursFloat/null作業時間（時間単位）
rateFloat/null全体に対する割合（%）
wait_beforeObject前フェーズからの待機時間
designObject設計フェーズ（requirementsと同構造）
codingObject実装フェーズ（requirementsと同構造）
testingObjectテストフェーズ（requirementsと同構造）
releaseObjectリリースフェーズ（requirementsと同構造）
paginationObjectページネーション情報
current_pageInteger現在のページ番号
per_pageInteger1ページあたりの件数
total_pagesInteger総ページ数
total_countInteger総件数

エラー時

ステータスコードエラー内容説明
400Bad Requesturlパラメータが未指定
401Unauthorized認証エラー
• トークンが無効
• 組織名が無効
404Not FoundIssueが見つからない

エラーレスポンス例

{
  "error": {
    "type": "bad_request",
    "message": "url parameter is required"
  }
}
{
  "error": {
    "type": "unauthorized",
    "message": "Unauthorized"
  }
}
{
  "error": {
    "type": "not_found",
    "message": "Not Found"
  }
}

使用例

エピックのツリーを取得（デフォルト）

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

エピックのツリーを孫まで取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ルートIssueのみ取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=0>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ページネーション指定で取得

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FEPIC-123&max_depth=2&page=2&per_page=5>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

ストーリーをルートとして取得

エピック以外のIssueもルートとして指定できます。その場合、指定したIssueがdepth=0となり、直下の子Issueがdepth=1で表示されます。

curl -X GET "<https://api.findy-team.io/api/external/v1/issues/process_time/tree?url=https%3A%2F%2Fexample.atlassian.net%2Fbrowse%2FSTORY-1&max_depth=1>" \\
  -H "Authorization: Bearer your-access-token" \\
  -H "X-Organization-Name: your-organization-name"

最新記事

イベント・セミナー

事例紹介

事例一覧